On #2729083: @encode becomes @endcode, some instances of misspelled @endcode tags are being fixed.

It would be good if we had a sniffer that detected unknown tags in documentation. We could whitelist the tags that are listed on https://www.drupal.org/node/1354 and if any others were detected in doc blocks, flag an error.

So for instance if someone used @returns instead of @return, or @encode instead of @endcode, their patch would fail the sniffer test, and we'd avoid having unknown tags in the docs.

Comments

jhodgdon created an issue.

borisson_’s picture

borisson_
Primary language Dutch
Location Mechelen, 🇧🇪
CreditAttribution: borisson_ commented

It might be possible to create such a whitelist for core, but since contrib/custom code can add it's own plugin types, I don't see how it would be possible to maintain such a list.

It's easier to catch @encode / @returns specifically and warn about those but I don't see a lot of value in that.

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

It should be possible to use a regular expression for plugin annotations. These are special because they look like:

  * @TypeOfPlugin('simple_id')

or

  * @TypeOfPlugin(
  *   a bunch of lines
  * )

They must have () so I think we can detect them with a regular expression. That is what the API module does.