We have 3 topics on api.drupal.org for Drupal 8 related to annotations. They need a little bit of work:
a) The "Annotations" topic needs to be moved from file core/modules/system/system.api.php into core/modules/system/core.api.php.
b) The "context definition plugin metadata" topic needs to have a better title (probably "Annotation for context definition") and a one-line description added to the top. See
https://www.drupal.org/node/1354#defgroup
for syntax.
c) The "Translatable plugin metadata" topic needs to have a better title (probably "Annotation for translatable text") and a one-line description added to the top. Again, see
https://www.drupal.org/node/1354#defgroup
for syntax.
d) The "Annotations" topic needs to have @see references to the other two, and the other two need to have @see references to the main Annotations topic. To make an @see reference, all you need is the machine name of the topic/group. So if the doc block says "@defgroup annotation", then the reference would say "@see annotation". @see lines should go at the end of a documentation block.
Comment | File | Size | Author |
---|---|---|---|
#11 | drupal8-fix-up-annotation-related-topics-2299677-11.patch | 5.71 KB | er.pushpinderrana |
Comments
Comment #1
jhodgdonAnyone want to do this?
Comment #2
gauravkhambhala CreditAttribution: gauravkhambhala commentedComment #3
gauravkhambhala CreditAttribution: gauravkhambhala commentedPatch does this job.
Patch does this job except "a one-line description added to the top" Could you guide me with the text here.
Patch does this job except "a one-line description added to the top" Could you guide me with the text here.
Patch does this job.
Comment #4
er.pushpinderrana CreditAttribution: er.pushpinderrana commented@gauravkhambhala, thankyou for contribution.
You should change Status to Need Review after uploading the patch so that your patch get through Test bot.
Comment #5
gauravkhambhala CreditAttribution: gauravkhambhala commented@er.pushpinderrana Thank you for the tip. I know this. I did not think the patch had everything, there will be more to it once my queries get answers. Anyway I will add another patch and get it reviewed again than.
Comment #6
jhodgdonThanks for the patch!
Both core.api.php and system.api.php ended up with:
in your patches. You just need to go into your editor at the end of both of those files and hit "Enter" and save.
For one-line descriptions... I would suggest:
context topic:
Describes how to use ContextDefinition annotation.
translatable topic:
Describes how to use Translation annotation for translatable user-interface text.
One more note: There should not be a blank line between the @defgroup line and the @{ line, so could you remove those in the context and translation topics?
Thanks -- the rest of the patch looks great!
Comment #7
gauravkhambhala CreditAttribution: gauravkhambhala commentedThank you for the inputs. Here is the updated patch.
Comment #9
er.pushpinderrana CreditAttribution: er.pushpinderrana commentedJust rerolled #7 patch as it unable to apply.
Comment #10
jhodgdonAh, I guess my suggestion for the "one-line" description for the translation topic is more than one line:
How about:
Describes how to put translatable UI text into annotations.
Other than that, looks good, thanks for the teamwork!
Comment #11
er.pushpinderrana CreditAttribution: er.pushpinderrana commentedThanks jhodgdon!
Please review updated patch, as incorporated #10 changes.
Comment #12
jhodgdonGreat, thanks!
Comment #13
alexpottCommitted 1371390 and pushed to 8.0.x. Thanks!