Problem/Motivation

All related plugin classes and interfaces for a plugin type need to be linked together in documentation, so that developers can discover how to make that type of plugin. Also, there should be a link to the plugin_api topic in their documentation headers, which tells how to make plugins in general. (See #2269389: [meta] Make sure plugin developer info is discoverable for discussion, if interested.)

For any plugin type, here are the classes and interfaces that need to be located and linked together:
- The interface for the plugin (if there is one -- most plugins have one)
- The base class for the plugin (if there is one -- most plugins have one)
- The plugin manager class
- The annotation class

Developers also need to know the plugin namespace that plugin classes have to be put into, in order to be recognized.

And it would be helpful for them to have a link to one working example of a plugin.

Proposed resolution

This issue is for: The InPlaceEditor plugin type

The specific tasks to be done:

a) Locate the annotation class, interface, base class (if there is one), and plugin manager class for this plugin type. Find a working example class too. And figure out what the plugin namespace has to be. There are notes below on how to do this.

b) Make sure that all these classes and interfaces are linked together with @see links or are mentioned in each other's documentation headers. Example of a @see link:

 * @see \Drupal\foo\bar\FooBarPluginInterface

c) Make sure that all of these classes and interfaces have:

 * @see plugin_api

in their documentation headers.

d) Make sure that the annotation class documents the plugin namespace like this:

 * Plugin Namespace: Plugin\Foo

e) In the Annotation class, also put in a line linking to the working example:

 * For a working example, see \Name\Of\Plugin\Class

Remaining tasks

See Proposed Resolution.

Note:

All of the added lines should go into the class or interface documentation block, meaning the documentation immediately before the class/interface declaration:

/**
 * (This is the interface documentation block/)
 */
class WhateverInterface extends Plugin {

Plain text lines like "Plugin Namespace: ..." should go before any @see or @ingroup lines, and the @Annotation line has to come last in any docs header.

Some notes on how to do this

You can find the annotation class on
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...

To find the a working example, look for a class in the Drupal Core code base that is annotated with the annotation class (using grep). For instance, if the annotation class is "Foo", search for a class that has "@Foo(" (without the quotes) in its documentation header.

Once you have located a working example, look at its class hierarchy (you can do this easily on api.drupal.org). It will most likely be extending a class called something like "FooBase", which would be the base class, and FooBase will most likely be implementing an interface called something like "FooInterface", which would be the plugin interface.

To find the manager class, take a look at the "Expanded class hierarchy of DefaultPluginManager" page:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Plugin!DefaultPlu...

Look for a class there called FooPluginManager or something similar.

Once you have found the manager class, look at its __construct() method. It will call parent::construct(), passing in the annotation class and the plugin namespace. Verify that the right annotation class is shown, and take note of the plugin namespace is (typically something like "Plugin/Foo".

User interface changes

None.

API changes

None.

Support from Acquia helps fund testing for Drupal Acquia logo

Comments

er.pushpinderrana’s picture

Status: Active » Needs review
FileSize
2.69 KB

Please review.

jhodgdon’s picture

Status: Needs review » Needs work

Thanks!

These two lines need a blank line between them:

+ * Plugin Namespace: Plugin\InPlaceEditor
+ * For a working example, see \Drupal\quickedit\Plugin\InPlaceEditor\PlainTextEditor

Also, I think the links to the Annotation classes have the wrong namespaces?

amitgoyal’s picture

Although I have added a blank line but not sure what's wrong with namespaces. Please clarify.

jhodgdon’s picture

The annotation class is \Drupal\quickedit\Annotation\InPlaceEditor, right?

The links in the base class, interface, and manager say:

+ * @see \Drupal\quickedit\Plugin\InPlaceEditor

"Plugin" in place of "Annotation".

amitgoyal’s picture

Status: Needs work » Needs review
FileSize
2.71 KB
1.67 KB

Oh yes, please review updated patch as per fixes in #4.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Thanks, looks good now!

Wim Leers’s picture

Component: documentation » quickedit.module
Status: Reviewed & tested by the community » Needs work
Issue tags: +Documentation
+++ b/core/modules/quickedit/src/Plugin/InPlaceEditorManager.php
@@ -12,9 +12,14 @@
+ * Provides an In-place editor manager.

s/I/i/

Wim Leers’s picture

One more:

+++ b/core/modules/quickedit/src/Annotation/InPlaceEditor.php
@@ -12,6 +12,15 @@
+ * For a working example, see \Drupal\quickedit\Plugin\InPlaceEditor\PlainTextEditor

Missing trailing period.

And why the fully qualified class names? All of these are in the same namespace already!

jhodgdon’s picture

We generally want fully-qualified class names in *all* documentation headers, according to standards.

And ... I generally agree a trailing . is a good idea, but not necessarily in this case where it directly follows a class name and it's only one line of docs...

The last submitted patch, 5: drupal8-inplace-editor-plugin-docs-2290269-5.patch, failed testing.

jhodgdon’s picture

Component: quickedit.module » documentation

Please leave this in documentation component.

jhodgdon’s picture

Component: documentation » quickedit.module

As requested, this is going back to quickedit.module so the maintainers can oversee this patch. If you get it to RTBC and want me to commit it, please move it back to the "documentation" component.

jhodgdon’s picture

This patch just needs a quick fix for #7 (an upper-case I needs to be lower-case i). Can someone please make a new patch?

er.pushpinderrana’s picture

Status: Needs work » Needs review
FileSize
2.71 KB

Thanks @jhodgdon!

Please review updated patch.

jhodgdon’s picture

Status: Needs review » Reviewed & tested by the community

Thanks, looks good to me! Let's give it a few days for the maintainers to review, then commit it.

alexpott’s picture

Status: Reviewed & tested by the community » Fixed

Committed 2212b4b and pushed to 8.0.x. Thanks!

  • alexpott committed 2212b4b on 8.0.x
    Issue #2290269 by amitgoyal, er.pushpinderrana | jhodgdon: InPlaceEditor...

Status: Fixed » Closed (fixed)

Automatically closed - issue fixed for 2 weeks with no activity.