[meta] Make sure plugin developer info is discoverable

+1 to adding that, the dynamic-ness of some plugin namespaces (aggregator, views) makes it non-greppable.

@plugin_namespace Plugin/aggregator/parser

Either that should be

@plugin_namespace Plugin\aggregator\parser

or

@plugin_subdirectory Plugin/aggregator/parser

Um.

PLEASE do not change "@defgroup annotation". That is a magic topic -- the API module finds all classes with @Annotation in their doc block and automatically adds them there.

We have another @defgroup topic in core/modules/system/core.api.php for the Plugin API, which hasn't been written yet. If we need another one for Plugin Annotations, we can add that too.

Anyway... There are all these different possible discovery methods for plugins. I agree that each plugin type needs documentation somehow on how to make a plugin class of that type discoverable (what namespace it needs to go in, what interface it needs to implement, what annotation it needs, etc.). I don't think we necessarily need a separate topic for the annotation namespaces, or a special way to group them, I just think each plugin type should have this documentation.

It doesn't matter to me whether the documentation goes into the plugin classes, the annotations, the interfaces, or topics/defgroups. Wherever it is, all of the relevant classes/interfaces should be linked together with @see references and/or "See \This\Class\Name for documentation on how to make Foo plugins" notes or @ingroup or whatever, and the documentation should exist.

I just don't think we need to invent a new way to document plugin namespaces -- we just need to make sure our existing types of plugins are well documented as to how to do them.

For instance, there are a couple of issues about documenting how to create plugins:
#2216533: Fill in topic/@defgroup docs for Entity API overview (needs review)
#1871762: Add detailed documentation explaining the block system's architecture (recently done)

And actually:
#2234439: Add a section for the plugin system to the API doc landing page (needs to be finished, may be a dup of other issues)

So I don't actually think we need this issue here. I think if particular types of plugins are not well documented, we should file issues to document them better, and on that other issue, we should make sure that the generic "how to do plugins" system is documented.

So mark this as a duplicate of #2234439: Add a section for the plugin system to the API doc landing page and add @ingroup references to it from specific implementations? That seems fine to me.

Marking as duplicate then.

OK, let's step back here.

So, we currently have:
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...

This automatically grabs every class that has @Annotation in its header and lists them. The documentation at the top is in system.api.php (and should be moved to core.api.php probably but that is a separate question).

By convention, the idea there (which we discussed on another issue a few months ago) is that the annotation class header for each type of plugin should explain how to make a plugin of that type, and/or have @see links to relevant classes and interfaces, such as probably the plugin manager class, the plugin interface, and any base classes that a developer might need. If there are annotation classes that do not have this information, we should file individual issues to get them added, or make a meta and do them all at once (or maybe this could be the meta). So the idea was that you could go to the Annotations topic, discover a type of plugin there, click the link, and either learn how to make that type of plugin directly, or at least have @see links to get you to that information.

We also are going to have a Plugin API topic, which currently is just a stub; that is issue #2234439: Add a section for the plugin system to the API doc landing page. That topic should generically describe how to define a plugin type, and how to define a plugin instance.

We also have separate topics for Entity and Block, which describe how to deal with those types of commonly-used plugins (you can see links on the D8 api.d.o landing page; those topics have been written).

So... Given all of that.... What other listings or documentation or topics in the area of plugins do you think we need, in addition?

I don't know how to make the plugin namespace convention discoverable... And I found a couple of related issues:

1. This one is about how the EntityType plugin annotation doesn't give you any of the things you need to put into the annotation:
#2189497: Object-based Annotation classes need links to interfaces
2. This one is about making sure the interfaces link to the annotation (the opposite direction)
#2099433: Adding @see comment to all of the plugin base classes pointing to their annotation classes.
I think we should close that one as a duplicate and do them together here.

So... Assuming that the Annotations topic is the place to go to discover plugins... I went through the list of annotations on
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...

Here is the list of the ones that are plugins, and my assessment of whether they are OK or not for docs. In my opinion, every one either needs:
a) A @ingroup so that under Related Topics it links to a topic that explains to make one of these plugins
b) Documentation in the header of: the plugin interface, plugin base class, plugin manager class, and plugin namespace, and a link to the Plugin API topic (@see plugin_api)
c) Or at least at a minimum, @see to the manager and interface classes. (These are all in the Annotations topic, so at least that topic will have a link to plugin_api, and the manager will give you the plugin namespace.)

And also, I think that the Manager, Interface, and Annotation classes should all have @see links to each other.

Here's the list of annotation classes for plugins:
- Action - has @see links, and other classes have @see back, so that is all good. No link to base class though?
- AggregatorFetcher - needs docs
- AggregatorParser - needs docs
- AggregatorProcessor - needs docs
- Archiver - has @see link to manager, OK; but manager isn't backlinked, and no links to interface and base class
- Block - has @ingroup to detailed topic, OK
- CKEditor - needs docs
- Condition - desperately needs docs (what is this even for???)
- ConfigEntityType - needs docs (@ingroup entity_api); should also have explanation as on EntityType of where to find the necessary annotation properties
- ContentEntityType - needs docs (@ingroup entity_api); should also have explanation as on EntityType of where to find the necessary annotation properties
- DataType - has docs and ingroup, OK
- Editor - needs docs
- EntityReferenceSelection - needs docs
- EntityType - needs docs (@ingroup entity_api)
- FieldFormatter, FieldType, FieldWidget - needs docs but there is already an issue taking care of this: #2287889: Field topic needs more info about plugins
- Filter - needs docs
- ImageEffects - needs docs
- ImageToolkit - has @see links to interface/manager, but not base class; no backlinks.
- InPlaceEditor - needs docs
- Mail - needs docs
- MigrateDestination - needs docs
- MigrateProcessPlugin - needs docs
- MigrateSource - needs docs
- Plugin and PluginID - probably should be added to @ingroup plugin_api on #2234439: Add a section for the plugin system to the API doc landing page; I'll make that happen on that other issue
- RestResource - needs docs
- SearchPlugin - needs @ingroup search
- Tip - needs docs
- Views* - there are defgroups for each type of plugin; need @ingroup to appropriate topics.

I'm updating the issue summary. The next step is to file a bunch of child issues.

I have added 1 child issue for the Action plugin, to use as a test (it's marked Novice, and we want to see if novices can tackle it as written; then will add additional issues for the other plugins or plugin groups).

I have also added 3 child issues for the plugin types that just needed @see added and stuff like that.

Let's see how this goes...

The Action test issue went pretty well! Based on the initial patch, which was nearly perfect, I added a few notes to the instructions and made issues for all of the other plugin types that also need documentation.

Once all the child issues are fixed, we can mark this one as fixed.

Isn't there another issue about this somewhere?

I seem to remember commenting that I would really like there to be a simple way to get a list of plugin types, so that Module Builder can help developers generate scaffold plugins.

https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro... has too many false positives to be useful programmatically -- there's things that don't look like plugins and things from Symfony too.

Not a great idea to assign an entire "meta" issue to yourself. :)

Regarding there being another issue, yes there was; it was the one where we made the @Annotations list automatically appear like @ingroup annotations, and made the @defgroup annotations. But you are right, that list includes more than just plugins.

My advice to someone trying to find actual plugin annotations would be to start with the Plugin annotation class and see what the class hierarchy is. That should list most/all plugin annotation classes.

Hello wonderful issue followers! You've done a great job -- there are only 5 open issues left in the "Child Issues" sidebar. Any takers?

I went through all the existing Annotations classes today and they're all good except for two open issues: one that had been outstanding for a while covering 3 Image classes, and one for DisplayVariant, which I just filed.

I just did patches for both of them.

These are all fixed now!