Field topic needs more info about plugins

Well, on #2234439: Add a section for the plugin system to the API doc landing page I was writing up some info about the plugin API, and making some links to the other topics we already have that are plugins. I noticed that the Field API topic(s) didn't say much about plugins. The Formatter and Widget topics do mention the plugins a bit, but I don't think they have the full needed information (plugin namespace, plugin interface, base class, and annotation class). And I didn't see any good description of how to define a field type, which I think (?) is also a plugin.

I don't think it needs to be too detailed... probably it can just say something like:

Field types are plugins with annotation class Foo, plugin interface Bar, base class Baz. Be sure to do xyz in order to ... [I don't know if there are any caveats but if there are, they should be mentioned too]. They need to be in namespace Blaz. See the @link plugin_api Plugin API topic @endlink for more information on how to define plugins.

Also... The annotation class... if it's like Entity annotation, and it doesn't actually give the items that you need to annotate, then we should also tell where to find that information. But if it's like most annotation classes, it will have all the things in it you need to annotate, and just linking to the class will be enough.

Oh and all those class mentions should have the namespaces.

Hope that makes some kind of sense?

Oh yeah, I thought of one more thing:

It seems to me that if you're on the topic about defining field types, the relevant classes/interfaces should be listed. So their docs headers all need to have an @ingroup.

Same for the widgets and the formatters topics.

Yes, something like that! Looks pretty good, thanks!

A couple of things to fix:

a)

  * @Annotation
+ * @ingroup field_types
  */
 class FieldType extends DataType {

The @ingroup has to go before @Annotation, and it should be separated by a blank line. Annotations are always supposed to be the last thing in a doc block.

b)

+ * \Drupal\Core\Field\FieldItemInterface. FieldTypes should extend from base
+ * class \Drupal\Core\Field\FieldItemBase. In order to implement

I think this should say "Field type classes usually extend base class ..." because:
- I don't think FieldTypes should be one word.
- Classes extend other classes, not "extend from".
- The base class is a convenience, not a requirement.

c)

In order to implement
+ * \Drupal\Core\Field\FieldItemInterface your plugin needs to implement the two
+ * public static functions propertyDefinitions and schema.

I think we can leave this out. To implement an interface, you definitely have to implement all its methods; that is just how interfaces work and we do not need to explain it.

d) Additional things to add to this patch:

1. On https://api.drupal.org/api/drupal/core!modules!field!field.module/group/... remove this (it isn't linking anywhere): "Field language API: Provides native multilingual support for the Field API."

2. On the Widgets and Formatter topics, make sure similar documentation is added, and similar @ingroup, to what you did for the Field Types topic.
https://api.drupal.org/api/drupal/core!modules!field!field.api.php/group...
https://api.drupal.org/api/drupal/core!modules!field!field.api.php/group...

They both are mentioning the interface and base class, but not the namespace or annotation class, and there are no ingroups.

3. I noticed on the Widget and Formatter topics, they link to their plugin manager classes. This is probably a good idea for the Field Types topic as well? And the Manager classes should have @ingroup too.

This issue is becoming part of another meta (at least, it will be a meta soon, I'm editing that summary).

Oh dang. I reviewed this and my review got lost. I must not have hit "save" hard enough. :(

So... this is mostly great!

Things I noticed:

a) The Formatter and Widget Annotation classes did not get @ingroup added to them.

b) There are a couple of classes that are mentioned in the docs that didn't start with \ on their namespace. They should.

c) I wasn't sure about the wording around annotations, such as:

+ * Field types are plugins with annotation class
+ * \Drupal\Core\Entity\Annotation\FieldType, and implement plugin interface
...

I think I would rather say "... are plugins annotated with ..." ... Maybe?

d) Could we also add @see plugin_api to the Field Types, Formatters, and Widgets topics doc blocks? That is not yet filled in but will be shortly on another issue.

I think that's all I found... really looking good, thanks!

WooHoo! We're there! Committed to 8.x.