Updated: Comment #1
A while back, api.drupal.org was set up with an Annotations topic:
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...
Automatically, every Annotation class (identified with @Annotation in the doc block, excluding core/vendor) is shown there, and there's some documentation on the @defgroup annotation block that tells a bit about annotation.
So far, so good... But today I found out on #2107429-9: EntityType annotation doc blocks do not meet our standards from tim.plunkett that in contrast to when this was set up, we are no longer documenting the components of all annotations on the Annotation classes. Instead, some of them have been converted to Object-based instead of Array-based annotation, and they are being documented on other classes and/or interfaces with get/set methods. So for instance, the EntityType annotation class doesn't document anything that you'd actually need to put in your @EntityType annotation to define an entity type.
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Entity!Annotation...
Add additional information to each of the object-based annotation classes linking to the interface/class that documents the get/set methods and annotation properties.
1. Propose wording about how to find docs for annotations for the @defgroup annotation block in core/modules/system/system.api.php, and make a patch. Don't want to do that now
2. [Done] Make a list of the existing Annotations classes on https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro... that need to be updated.
| Annotation class | Interface(s) with documentation |
|---|---|
| core/lib/Drupal/Core/Entity/Annotation/EntityType.php | core/lib/Drupal/Core/Entity/EntityTypeInterface.php |
note: It turns out that EntityType is the only object-based annotation at this time.
3. Make a patch that puts additional documentation on all the annotation classes listed in (2) to link to the appropriate classes and interface(s).
None.
None.
| Comment | File | Size | Author |
|---|---|---|---|
| #16 | object-based-annotation-classes-doco-2189497-16.patch | 808 bytes | paulh |
| #12 | object-based-annotation-classes-doco-2189497-12.patch | 808 bytes | paulh |
| #9 | object-based-annotation-classes-doco-2189497-9.patch | 885 bytes | paulh |
| #2 | annotation-doc-2189497-2-D8.patch | 506 bytes | richard.c.allen2386 |
Comments
Comment #1
jhodgdonI am marking this as a Novice project, and I've updated the issue summary with several tasks that are certainly open to new or experienced contributors. Please help out!
Comment #2
richard.c.allen2386 commentedI was looking at the original issue and started all the commotion about it being deprecated and moved around. I'm trying to figure out the documentation and how it works to start work on the issue but we're at a loss.
As far as I can tell their are multiple annotation types now in core https://drupal.org/node/2086397 and each base class should have a particular 'type' of plugin declaration (this may not be the correct terminology). I wrote up a little patch to get the issue started, is the the type of change we are talking about for the second and third part of the tasks? If so I can continue up the issue a bit and move it further along I'd just like to be sure I'm doing this correctly.
Comment #3
jhodgdonUmmm... What I was trying to say in the issue summary is that on the Annotation class, to have an @see to the Interface class. Vice versa is probably good too, but the @see on the Annotation class will give people a link from the Annotations topic to documentation on how to annotate their plugin classes.
Comment #4
richard.c.allen2386 commentedSorry I'm still wrapping my head around this namespace/psr-0 stuff.
An annotation class would live at /core/lib/Drupal/Core/Field/Annotation/FieldBase.php in my example correct? I don't see this class on HEAD in 8.x so I'm a bit confused at how the @see you think we need fits in. Can you possible post a small patch pushing mine to the next step so I can see the example? I realize you gave the EntityType.php above but it's still not 100% clear to me after looking at the classes for a while.
Edit: I realize that you may mean there is a drupal core AnnotationBase.php or something similar, I'll look into it hopefully a bit tonight to see if I can figure that out.
Comment #5
jhodgdonLet's see, I haven't looked at field annotation.
So here's my thought process. First I go to the Annotations topic at:
https://api.drupal.org/api/drupal/core!modules!system!system.api.php/gro...
I scroll down to FieldType, which links to:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Field!Annotation!...
So that is the Annotation class for defining Field Types.
It looks like that Annotation class already has a bunch of documentation on it of the components you would need in order to define a field, so perhaps this class hasn't been updated like EntityType was? I really haven't been following this process (this whole thing was news to me yesterday), so I think we need to get someone who actually knows what is going on here to comment. I'll ask tim.plunkett, since he posted the original comment that sparked this issue.
Comment #6
jhodgdonDang. I am really sorry.
So, I just had a conversation with tim.plunkett in IRC and it turns out that EntityType is the only annotation class for which there is a problem, because it has been changed from being a simple array-type plugin annotation/discovery, to an object-type plugin annotation/discovery. All of the other annotation types are array-type and they are properly documented in the annotation classes.
So what we need is just for the EntityType annotation class (in core/lib/Drupal/Core/Entity/Annotation/EntityType.php) to have some information added to it, a paragraph saying something like this:
(thanks to Tim for clearing this up for me).
I'll update the issue summary and title.
Comment #7
jhodgdonComment #8
paulh commentedComment #9
paulh commented@jhodgdon is this what you meant? Just cleaned up the advised text a bit and added a @see to the doco.
Comment #10
paulh commentedComment #11
jhodgdonLooks good! The only thing is that instead of putting in the HTTP link to a specific api.drupal.org page in
you should instead do @see \Fully\Namespaced\Name\Of\Class
The reason is that this documentation block may have a very long life (Drupal 8, Drupal 9, Drupal 10, ... plus we may have 8.0.1 etc. so the URLs could change), and also there are other sites like api.drupal.org that would want the links to stay internal to their site.
Thanks!
Comment #12
paulh commentedUpdated as per suggestion to reference the fully namespaced class and re-rolled the patch.
@jhodgdon: thankyou for your patient guidance. I really appreciate it.
Comment #14
paulh commented12: object-based-annotation-classes-doco-2189497-12.patch queued for re-testing.
Comment #16
paulh commentedTry again.
Comment #17
jhodgdonThanks! That looks good. The previous patch ran into both of the random test failures that is being tracked down today and yesterday -- so it wasn't your patch that was the problem.
Comment #18
paulh commentedThanks for the feedback - the test failures did have me scratching my head for a bit. Cheers.
Comment #19
jhodgdonThanks again! Committed to 8.x.
Comment #21
jhodgdonTest bot is too fast. Queued patch above for retest just before I committed it.