Problem/Motivation
Issue
#1966246: [meta] Introduce specific annotations for each plugin type
is introducing specific plugin annotation classes for various plugin types, so instead of using @Plugin() to annotate typical plugins, we will be more likely to use @EntityType() or another specific type. Each annotation class has @Annotation in its documentation block.
We need to update some documentation, and make a group/topic definition to list these plugin annotation types (see specifics below).
Proposed resolution
These steps need to be done (from comment #11):
- Update node/1354 so that instead of @Plugin, it describes @(AnnotationTypeName) instead.
- Update node/1354 to describe @Annotation itself.
- Update the API module so it can handle the generic @AnnotationTypeName (making it into a "Plugin annoatation @code/@endcode" section like it is doing for @Plugin now), as well as transforming @Annotation to @ingroup annotation. Issue: #1990050: Support more flexible plugin annotation
- Make a patch defining @defgroup annotation that describes annotations.
- Update the online documentation for plugins: http://drupal.org/node/1882526
Remaining tasks
All tasks still need to be done.
User interface changes
The only changes on this issue to Drupal Core are to API documentation.
API changes
The only changes on this issue to Drupal Core are to API documentation.
Related Issues
#1966246: [meta] Introduce specific annotations for each plugin type
#1969970: How to document needed @Translation on dedicated annotation classes
#1990050: Support more flexible plugin annotation
Original report by jhodgdon
Coming from
#1969970: How to document needed @Translation on dedicated annotation classes
It appears that our standards on plugin annotations
http://drupal.org/coding-standards/docs#Plugin
are outdated, in that it is more likely that someone will be using a specific class instead of Plugin, so the tag will be flexible, like
@EntityType
So, I think we need to:
a) Update the docs standards to make this clear.
b) Update the API module to deal with this.
I'm not currently quite sure what the right way to do either is, so filing this issue to discuss both...
On (b), webchick suggested on the other issue that if the API module encounters @[CamelCaseClassNamePattern] it should do what it's currently doing for @Plugin. What it's currently doing is detecting @Plugin(...) at the very end of the doc block, and replacing this with a Plugin annotation H3 header, with the @Plugin(...) as if it was in @code/@endcode. This seems fairly reasonable, since I don't think any of our other @tags start with a capital letter. In addition, I think we could make the ClassName turn into a link to the class.
Thoughts? Any suggested rewrites of the standards page section?
Comment | File | Size | Author |
---|---|---|---|
#26 | 1970900-defgroup-26.patch | 1.6 KB | jhodgdon |
#20 | 1970900-defgroup-20.patch | 1.61 KB | jhodgdon |
#19 | 1970900-defgroup-19.patch | 1.63 KB | jhodgdon |
#17 | 1970900-defgroup-17.patch | 1.4 KB | jhodgdon |
#16 | annotations.png | 72.67 KB | jhodgdon |
Comments
Comment #1
jhodgdonSome suggestions from the other issue:
a) dawehner: Use Doctrine
===> This is not all that feasible. The API module needs to be able to do this in Drupal 7, and besides it doesn't really want to understand plugin annotation, it just needs to display documentation/code.
b) EclipseCG - "I think all of these top level classes that are replacing @Plugin are going to be extending it (if that's helpful to api.module)."
===> This doesn't actually help, because when parsing a given file for documentation, the other files that define the class hierarchy are not loaded, so there's not an obvious way to know that the class name extends Plugin.
Comment #2
tim.plunkettAll of them will have
Not sure if that helps either.
Comment #3
jhodgdonAs a note, it looks like the docs section on how to write plugins also needs updating:
http://drupal.org/node/1882526
Comment #4
jhodgdonSo, you have to think about how the API module works: it's parsing one file at a time, and you do not know what order they will be parsed in, or even if the classes being extended are part of the same project (could be contrib etc.). So basically:
- The API module is not going to know about Doctrine since you could parse D8 code from a D7 version of the API module, for instance.
- The API module does not know anything about any class hierarchies in any particular version of Drupal or any particular contrib module.
- All you can be sure it knows about at the moment of parsing is what is in that particular file.
So if you are saying that in the file for class MyEntityType, that the annotation is @MyEntityType and that MyEntityType itself extends Plugin, that would be fine. But I think this case that MyEntityPlugin would have annotation for @EntityType and that MyEntityType would extend something like EntityTypeBase, right? In which case I don't think the fact that EntityType extends Plugin helps us at all.
Comment #5
jhodgdonI'm also seeing this in core/lib/Drupal/Core/Annotation/Translation.php :
What does that mean, and should we document it somewhere?
Comment #6
tim.plunkettWell, that's the @Translation we've been discussing in the other issue.
At the moment, there are three classes that directly implement AnnotationInterface:
Plugin
PluginID
Translation
I have no idea if we're planning to add any more, most will extend the first two.
Comment #7
jhodgdonUm. So does the API module need to do something special with @Annotation or should it just continue to ignore it?
Comment #8
tim.plunkettThe @Annotation acts (among other things) as Doctrine's "@ingroup annotation". If we can treat it as such and not have
That'd be good. But having that @Annotation is a hard requirement.
Comment #9
jhodgdonDo you have a @defgroup annotation somewhere? If so I could definitely special case @Annotation in the API module to make it be a synonym of @ingroup annotation. If there is not a defgroup somewhere with a description of what the group/topic is, there isn't much point. :)
Comment #10
tim.plunkettWe need to add a defgroup.
Comment #11
jhodgdonI see from the patch on #1967294: Add a dedicated @EntityType annotation that these Plugin types also have the @Annotation tag...
So, we definitely need to have a @defgroup annotation that describes annotations, and if I make the API module treat "@Annotation" as "@ingroup annotation", we'll be set.
So.... It looks like what we need to do for this issue is:
a) Update node/1354 so that instead of @Plugin, it describes @(AnnotationTypeName) instead.
b) Update node/1354 to describe @Annotation itself.
Here's some proposed documentation -- I'll clean it up somewhat before adding it to node/1354 but can someone check it for accuracy in the wording about annotations etc.?
I think what I'll do is add this to the tag reference in a section called "@Annotation and other plugin annotation", and I'll keep the link that's currently in the @Plugin reference section to the page on how to write/annotate plugins.
c) Update the API module so it can handle the generic @AnnotationTypeName (making it into a "Plugin annoatation @code/@endcode" section like it is doing for @Plugin now), as well as transforming @Annotation to @ingroup annotation
d) Make a patch defining @defgroup annotation that describes annotations.
Comment #12
jhodgdonToday I filed an issue for the API module changes to support generic @AnnotationClass:
#1990050: Support more flexible plugin annotation
We need to do the rest of this sooner rather than later!
Comment #13
jhodgdonI just created an issue summary for this issue.
I also just updated node/1354. Here is the updated section:
http://drupal.org/coding-standards/docs#Plugin
And here is the diff:
http://drupal.org/node/1354/revisions/view/2698986/2702142
Suggestions/comments welcome. :)
Does someone want to make an @ingroup annotations documentation block? My next API module task will probably be to support this stuff in the API module, and it would be good to have the @ingroup in place.
Comment #14
jhodgdonBump! We still do not have a "@defgroup annotation" docblock, and we need one! I'm taking care of the API module issue now, but when it's deployed it would be nice if we did have a topic to go with the references to this defgroup. Maybe I'll make a patch though, haven't done that in a while for core. :)
Also, I don't think anyone has reviewed my changes to the documentation standards. Can someone please do that?
Comment #15
jhodgdonAlso it would be great if someone who knows this stuff better than I do would take a look at https://drupal.org/node/1637614 -- I think it needs updating. The parent page is also rather ... ucky.
Anyway, here's a first pass at a patch for the annotation defgroup (I am running it through the API module now to verify that the @code section comes out right, and will report back with a screen shot in a while). Can someone review what I wrote and hopefully tell me where I've gone wrong and maybe fix it up?
Comment #16
jhodgdonAh, the file I added this to finished being parsed. The @code part worked, see screenshot from my API test stie. (But read the actual patch for the text I put there because I'm not sure whether this version is the latest from the patch or not, my test site is in the middle of a large parsing run from a git pull on 8.x).
Comment #17
jhodgdonNew patch, with better indentation and it turned out I didn't need to worry about the @ signs in the code block after all.
Comment #18
tim.plunkettIt is true that plugins are the only code we use annotations for, but they are not tied to plugins at any level.
We use "metadata" almost everywhere else. 300+ of that, 6 of meta-data
Because of escaping slashes, I find it easier to grep for "@EntityType" than "use Drupal\Core\Entity\Annotation\EntityType"
Comment #19
jhodgdonThanks for the review! How's this? [small patch, I didn't do an interdiff, sorry]
By the way, you can find classes that "use" a particular class now on api.drupal.org... oh wait, that might not be deployed yet. Well, soon you'll be able to. There's a section on a class page that says "N files declar their use of ClassName". I need to deploy the latest and greatest API module out there soon, lots of new features!
Comment #20
jhodgdonAfter discussing this with timplunkett, msonnabaum, and larowlan in IRC, I have revised the last paragraph to remove references to plugins.
Comment #22
jhodgdon#20: 1970900-defgroup-20.patch queued for re-testing.
Comment #23
EclipseGc CreditAttribution: EclipseGc commentedWe shouldn't be citing 'module' in the annotation anymore. We're automatically adding a 'provider' to the returned plugin definitions these days, and we should systematically remove manual module declarations.
Eclipse
Comment #24
jhodgdonUm. Is that relevant to the patch or related to something else?
Comment #25
tim.plunkettJust that this line needs to be something else not 'module', since we're removing those from every annotation.
Comment #26
jhodgdonAh. OK, how about this? I just changed the example for the annotation to take some lines from the Comment entity class.
Comment #27
jhodgdonbump. Can we get this reviewed? I would really like to have this @defgroup on api.drupal.org ...
Comment #28
tstoecklerI agree, this would be super useful. Read through it and couldn't find any problems. Let's do it.
Comment #29
webchickCommitted and pushed to 8.x. Thanks! Looking forward to seeing this used.
Comment #30
webchickAhem.
Comment #31
jhodgdon@webchick #29: The great thing is that it is *already* being used, because any time someone puts @Annotation in a docblock to define an annotation class, the API module treats it as @defgroup annotation. So as soon as api.drupal.org catches up to your commit (thanks! I didn't want to commit my own patch), we should have a fully populated topic listing all of the annotation classes. Magic! :)
Comment #32
webchickOoooh! :D I like magic!! That's awesome!
Comment #33.0
(not verified) CreditAttribution: commentedMake an issue summary