Update standards doc on plugin annotations; add @defgroup annotation

Some 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.

As a note, it looks like the docs section on how to write plugins also needs updating:
http://drupal.org/node/1882526

So, 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.

I'm also seeing this in core/lib/Drupal/Core/Annotation/Translation.php :

 *
* @Annotation
*/
class Translation implements AnnotationInterface { 

What does that mean, and should we document it somewhere?

Um. So does the API module need to do something special with @Annotation or should it just continue to ignore it?

Do 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. :)

I 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.?

Plugin annotation

@Annotation goes at the very end of a class documentation block to indicate to Doctrine that the class is a Plugin Annotation Type class. The API module displays these classes as if they had @ingroup annotation in their documentation blocks (you do not need to add the @ingroup if you have @Annotation in the documentation block).

To annotate a plugin class of a particular type, add a section at the very end of the class documentation block similar to this:

@EntityType(
   (I'll insert the annotation we currently have for the @Plugin reference on node/1354 here)
)

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.

Today 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!

I 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.

Bump! 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?

Also 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?

Ah, 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).

New patch, with better indentation and it turned out I didn't need to worry about the @ signs in the code block after all.

Thanks 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!

After discussing this with timplunkett, msonnabaum, and larowlan in IRC, I have revised the last paragraph to remove references to plugins.

#20: 1970900-defgroup-20.patch queued for re-testing.

Um. Is that relevant to the patch or related to something else?

Ah. OK, how about this? I just changed the example for the annotation to take some lines from the Comment entity class.

bump. Can we get this reviewed? I would really like to have this @defgroup on api.drupal.org ...

@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! :)