Add a section for the plugin system to the API doc landing page

Good idea! We have some documentation already at
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...

I think we need both... Can you put an @see to that topic in this patch though as at least a start to linking them together (and maybe an @see in the Annotations topic back to this one)?

This may be a duplicate of another issue, which I cannot find at the moment, but anyway... needs to be on the parent meta.

#2264047: [meta] Document service definition tags was marked as duplicate. Bumping this one to critical per that issue.

The previous patch is out of date. On another issue (not sure which), we added a stub section for the Plugin API:
https://api.drupal.org/api/drupal/core!modules!system!core.api.php/group...
and it is in core.api.php.

It is not yet linked from the API landing page though.

So what we need to do is write the section and link it on the landing page.

And as a note, the issue that was marked as a duplicate of this was #2269389: [meta] Make sure plugin developer info is discoverable. Comment #3 has the wrong link.

I'm looking at this issue at the core sprint today. In a previous comment jhodgdon said that we need to link this documentation to the landing page and remove the extraneous plugin doc declaration from the patch.

However that would mean I could find the "plugin" on https://api.drupal.org/api/drupal/8. Since I can't then the plugin link needs to be added.

This patch reduces the previous patch to what is necessary to get the plugin system in the list of other APIs that need visibility.

Created an outline of topics that should be included and filled out later about what plugins are and how to use them. Also assigning it to me for the next week while I flesh that out.

Um. The patch in #7 has a bunch of unrelated stuff in it? Looks like the wrong patch file was uploaded?

Patch in #6 is fine...

@cosmicdreams: Are you still working on this? If not, I have some time to do some writing and would like to assign this to myself.

In any case, I found the list of topics buried in the patch in #7:

+ * Plugins is an overloaded term in Content Management Systems. In Drupal a plugin is used to extend the system by providing
+ * additional implementations of configurable objects.  Out of the box, Drupal provides many different kinds of plugins:
+ *
+ * - Action:
+ * - Archiver:
+ * - Condition:
+ * - Contextual link:
+ * - Blocks:
+ * - Field Formatter:
+ * - Field Type:
+ * - Field Widget:
+ * ...
+ * - TypedConfig:
+ *
+ * Creating a simple plugin
+ * Walkthrough creating a block
+ *
+ * What is a derivative?
+ *
+ * What is a plugin discovery?
+ *
+ * What is a plugin discovery decorator?
+ *
+ * What is a plugin factory?
+ *
+ * What is a plugin mapper?
+ *
+ * What is a plugin manager?
+ *
+ * Creating a plugin manager
+ * @todo finish writing this

Some comments on this:
a) First paragraph... I wouldn't talk about what other systems do, just describe what plugins are in Drupal.

b) I don't think we should or need to provide a list of all the plugin types here. Maybe list 2 or 3 key examples. And please please do not use the term "out of the box". You can refer to "Drupal Core".

c) This should not be a tutorial, so don't include a walkthrough at all. Instead, refer to separate (existing) topics on the Block API and Entity API as examples (note: patch for the Entity API documentation is still needing review: #2216533: Fill in topic/@defgroup docs for Entity API overview). And link to the more comprehensive docs on drupal.org. The existing Block and patch for Entity topics should give you an idea of what we're looking for here.

d) The rest looks like a good list of the topics to be covered, but I'm not sure each one needs to be a section, and I don't think I would actually make section headers that are questions like that. Again, look at existing topics for guidance in the level of detail and style.

So... Let me know if you are still working on this. If not, I'd be happy to write the first draft and it would be great if you could review it if I do that. Thanks!

@cosmicdreams: I have tried to ask here and tried finding you in IRC but I am getting no response.... This really needs to get done soon, as it is a very much needed piece of documentation.

So, I'm going to go ahead and assign this issue to myself. If you are still working on it, or plan to sometime in the next few days, please assign it back to yourself. Otherwise, I'll take it up tomorrow probably. Thanks!

Whoops. We have some places in core.api.php linking to "plugins" and some to "plugin_api" (in other words, two machine names for the topic). I checked and there aren't any references yet outside of core.api.php. I chose plugin_api for the machine name.

Anyway... Here is my first pass at this documentation. I tried to strike a balance between completeness and length... the section on drupal.org at https://drupal.org/developing/api/8/plugins needs some serious work too!

I'm sure this has some typos and probably misinformation in it. A review would be helpful!

No interdiff; this is not based on any previous patch.

On #2269389: [meta] Make sure plugin developer info is discoverable I was reviewing the docs for various annotation classes. Realized probably the Plugin and PluginID annotation classes need to have @ingroup plugin_api so that they link back to this documentation. I'll do that shortly.

Here we go. And this is probably not really Critical.

1. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * interface. Each plugin type is managed by a plugin manager class, which uses
   

   I would leave out class or use service.

2. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * - Plugin derivatives: Allows a single plugin class to present itself to the
   + *   user interface as multiple plugins. Example: the Menu module provides
   

   I would leave out "to the user interface", that depends on how it's used, it exposes itself to everything as multiple plugins.

3. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * - Plugin bags: Allows a single plugin to have zero or more instances
   + *   configured by administrators on the site.
   

   Not sure if that's correct/makes sense. probably want to check with @tim.

4. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * There are two things a module developer may need to do with plugins:
   + * - Define a completely new plugin type: see @ref sec_define below.
   + * - Create a plugin of an existing plugin type: see @ref sec_create below.
   

   There's also a third point. Interacting with plugins. Both for the ones you defined and often you also do something with plugins from someone else and use them somehow.

   For example, core contains generic plugins like blocks and conditions that aren't just used by block.module but also by page manager in contrib and so on.

   Doesn't need to be huge, just cover the basics like asking the plugin manager for the definitions (getDefinitions()/getDefinition()) and creating instances (createInstance()). Everything of top of that is then specific to the given plugin type, so write something fancy like "consult the documentation for the given plugin type" :)

5. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * See https://drupal.org/developing/api/8/plugins for more detailed
   + * documentation on the plugin system. There are also specific topics for
   + * particular types of plugins:
   

   Maybe mention somewhere that those are just examples? Views alone has ~20 plugin types and core probably 40+

6. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + *   of your type. The base class usually extends
   + *   \Drupal\Component\Plugin\PluginBase, \Drupal\Core\Plugin\PluginBase, or
   

   should extend the core implementation, I wouldn't refer the other one (only relevant for someone who wants to use it without drupal).

   On the other site, there are separate base classes like context aware..

7. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * - YAML: Plugins are listd in YAML files. Drupal Core uses this method for
   + *   discovering local tasks and local actions.
   

   listed.

   Yaml is only recommended when most plugins use the same class, there's no logic, just the definition that is relevant (it's kind of like a global derivate).

8. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * - Static: Plugin classes are registered within the plugin manager class
   + *   itself. Static discovery is only useful if modules cannot define new
   + *   plugins of this type (if the list of available plugins is static).
   

   it's also possible to mix discovery together, both yaml and static also have annotation decorators. (might be worth mentioning on it's own).

   The only real use case of this in core is afaik validation constraints, where we provide defaults for symfony constraints where we can't add annotations.

9. +++ b/core/modules/system/core.api.php
   @@ -968,17 +969,169 @@
   + * The remainder of this documentation will assume Annotation-basd discovery,
   

   based

10. +++ b/core/modules/system/core.api.php
    @@ -968,17 +969,169 @@
    + *   need to provide. Most plugins have at least $id: a unique identifier,
    + *   usually a string.
    

    not sure if something else than an id is even possible? integer might work but doesn't make much sense :)

11. +++ b/core/modules/system/core.api.php
    @@ -968,17 +969,169 @@
    + * Some configurable plugin types allow administrators to create zero or more
    + * instances of each plugin, each with its own configuration. For example,
    + * a single block plugin can be configured several times, to display in
    + * different regions of a theme, with different visibility settings, a
    + * different title, or other plugin-specific settings. To make this possible,
    + * a plugin definition needs to include what's known as a plugin bag.
    

    The plugin bag doesn't really contain the configuration, that is (for example) in the block config entity.

    The bag is a runtime only container that is initialized with the configuration and the plugin manager and lazy-loads the plugins (which is the main use case).

    Saving configuration and instantiating plugins is also possible without plugin bags (and the majorit of config entities/plugins don't use it right now, as it's relatively new) and it's even possible to use it without config entities or a very different case than blocks (like entity form display stores configuration for all widgets of a given entity type/bundle/form mode).

    That said, plugin bags are becoming the standard and should be pushed, but it might be confusing if someone reads this and then looks at field plugins where are very different to this :)

12. +++ b/core/modules/system/core.api.php
    @@ -968,17 +969,169 @@
    + * Note: before reading this section, familiarize yourself with the information
    + * in @ref sec_define above.
    

    Not sure if this makes sense, as you don't need to know most of the things there to just define a plugin.

    Maybe it's even worth mentioning the most straight-forward way of creating a new plugin of a given type: Look for an example, copy it and update namespaces/classname/annotation and then the implementation? That's after all one of the main advantages of plugins/classes over multiple hooks. it's all contained in a single file so it's easy to duplicate and then change.

Discussion in IRC: We're I think moving the PluginID annotatation class to a test module. So I've taken out the @ingroup I added in #13.

@Berdir: Thanks for the review in #14! I think I have addressed all the issues.

thanks looks good.

Committed and pushed to 8.x. Thanks!