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 EntityReferenceSelection 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.
Comments
Comment #1
pushpinderchauhan commentedNo Interface and Base class found for this. Please review attached patch.
Comment #2
pushpinderchauhan commentedRerolled patch #1.
Comment #3
jhodgdonThanks!
These two lines need a blank line between them:
Also, there are no links to the SelectionInterface plugin interface or SelectionBase base class in this patch?
Comment #4
pushpinderchauhan commentedAdded interface and base classes in this patch.
Comment #5
jhodgdonLooks good now, thanks!
Comment #6
amitgoyal commentedIt's always better to provide interdiff for subsequent patches as it helps others to easily identify changes in that patch.
Please refer to creating an interdiff documentation steps https://www.drupal.org/documentation/git/interdiff.
Comment #7
jhodgdonSorry, I was about to commit this but I noticed this problem:
That line should not have been removed. Actually, this text has links already to the interface and the base class (although I think the namespaces are possibly wrong and the Base class namespace needs to start with \). So on this class, instead of adding @see again, we should just have the @see to the plugin manager class and fix up the links in the text that was already there.
Comment #8
pushpinderchauhan commented@jhodgdon thanks!
Please review attached patch, included your suggested changes.
Comment #9
jhodgdonOh gracious. Once again I was about to commit the patch, but checked it over... The entity reference selection documentation had some problems, including totally misleading descriptions for some things, and references to classes/interfaces that didn't exist any more.
So, here's another patch (this was much easier to do than writing out the problems in the current patch).
I am moving this temporarily into the entity reference component so the maintainers can review the docs changes.
Comment #10
jhodgdonSome notes on the previous patch/interdiff:
- I removed a paragraph that had a bunch of incorrect info in it, because once I got rid of the incorrect info, there was nothing left that hadn't already been said in the one-line description (this is in the Interface).
- @see lines need to go above plugin annotation (this is in the Base class)
Comment #11
amitgoyal commentedMinor fix "entity reference selection" => "Entity Reference Selection".
Comment #12
jhodgdonThanks, good catch!
Comment #13
joshi.rohit100As \Drupal\entity_reference\Plugin\Derivative\SelectionBase is added in \Drupal\entity_reference\Plugin\entity_reference\selection\SelectionBase. So, I think it should be added with others also.
Comment #14
jhodgdonUm, that interdiff is weird, Did you just make a diff of the two patch files? ?!?
Anyway, the latest patch is fine. ... I wrote quite a bit of the current patch. Therefore I should probably not be the person to review it and mark it RTBC. Could someone else please review?
Rohit, Amit, or Pushpinder -- would you like to review it and mark "Reviewed and tested by the community" if you think it is fine? We all worked on the patch, but as long as at least 2 of us think the latest patch is fine, that is probably good enough. Thanks!
Comment #15
pushpinderchauhan commented@joshi.rohit100, it was great caught by you. Thanks!
@jhodgdon, I corrected following two things in above patch:
1. Whitespace error.
2. In
entity_reference/src/Plugin/Derivative/SelectionBase.phpinterface class was missing.It seems good now, so moving to RTBC.
Thankyou All!
Comment #16
jhodgdonOK, still looks good to me too!
Comment #18
amateescu commentedThe patch looks good to me as well, still needs a reroll though :)
Comment #19
g3r4 commentedI've rerolled the patch, uploading for testing
Comment #20
g3r4 commentedChanging status to needs review
Comment #21
jhodgdonReroll looks good, thanks!
Comment #22
jhodgdonThanks again everyone! Committed to 8.x.