On Drupal Core issue, we were discussing how to document "service tags". A bit of background: Drupal 8 adopted Symfony's concept of Services. When you define a service, it can be tagged. But we do not have documentation on what the tags mean. We need a way to document them.
Adopt a new documentation tag @service_tag, with syntax similar to:
* @service_tag foo * Documentation for foo tag goes here. Explain what the tag means, and note that services tagged * with this tag should implement this interface. Also reference related classes, such as collector classes. * If the tag has parameters, use a syntax like this to document them: * - parameter1: Description of parameter 1. * - parameter2: (optional) Description of optional parameter 2. The default parameter2 is x.
This block of documentation would be put into a class or interface header related to the service tag, such as (in rough order of preference):
- An interface that services with this tag need to implement.
- A base class that services with this tag can extend.
- A service collector class that collects services with this tag.
- Some other relevant class, if none of the above applies.
Adopt or modify this standard.