find a standard way to document plugin types in api.php files

Splitting this off from #1966246: [meta] Introduce specific annotations for each plugin type.

My comment there:

If you look at https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Annotation..., compared to https://api.drupal.org/api/drupal/modules!system!system.api.php/function... --

- we've lost the general intro to the concept
- we've lost readability. The list of class properties is much harder to read down that the properties docblock we had for the hook
- we've lost sample code
- that means we've also lost the sample values for each property that are given in the sample code

Furthermore, there are new concepts in the plugin system that developers need to know about but which aren't represented here:

- what's the subdirectory to use for the plugin?
- what's the name of the service to get the plugin manager?

Another point to consider is that there has been talk (on IRC) lately of how useful Module Builder will be for getting developers accustomed to working with D8, and with coding some of the complexity of classes that D8 requires.

I made a rough start on a module builder generator for a plugin: #2086181: plugin generator.

However, in order for that to be useful, there's a bunch of information that needs to be available in a form that can be parsed:

- the service name
- the plugin class
- the plugin subdirectory
- the plugin namespace
- the annotation class
- sample code for the annotation

We'd need all of the above to be able to provide a similar experience when using MB to create plugins as we did for using MB to create hooks.

Compare: asking MB for 'hook_entity_info' got you:

- function already named with the right parameters
- sample function body

We'd want to be able to ask MB for 'entity_type' or 'EntityType' or whatever, and get:

- the folder structure
- the plugin file
- the annotation, with sample values
- the plugin class with the parent class
- sample class methods

To achieve that, I think we need to define sample plugins in api.php in the same way we define sample hooks.

Furthermore, we need:

- a standardized name for a plugin type. Eg, for entity types is it EntityType or the string you pass to get the service?
- standardized ways of documenting plugin subfolder, annotation class, and so on, so that that data can be retrieved programmatically