- 🇫🇷France fgm Paris, France
@chx just made me notice that 🐛 False positive in twig scanning, with reproducer Fixed is a consequence of this.
Right now there's no way for people to discover what the tags applied to services mean, or what tags exist, aside from reading the (currently incomplete) API page https://api.drupal.org/api/drupal/core!core.api.php/group/service_tag/8 or from going to https://api.drupal.org/api/drupal/services/8 and looking at the Tags column (and filtering by tags) [This latter is a good way to find out what services have a given tag, but not a good way to learn what the tags are supposed to be.]
a. Hopefully, most service tags have a corresponding interface that the service with that tag needs to implement. (The idea is that the service implements the interface, and another class that collects services with that tag will collect them and call one or more methods on the interface on each of the services with that tag.)
So, if a tag is associated with an interface, add documentation for that tag to the interface, like this:
* @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.
* - parameter1: Description of parameter 1.
* - parameter2: (optional) Description of optional parameter 2. The default parameter2 is x.
Example: ParamConverterManagerInterface is a good place to document the paramconverter tag in - { name: service_collector, tag: paramconverter, call: addConverter }
Some service tags have parameters. We need a way to document them, too.
b) If a service tag exists but there isn't an interface associated with it, find another relevant class to put the service tag documentation on, such as a class that implements CompilerPassInterface, which collects the services with that tag and uses them. In this case, the documentation should explain what methods need to be present on the service class (since there isn't an interface for them).
Example -- RegisterSerializationClassesCompilerPass could be a place to document the normalizer and encoder tags, since this class collects them, if there isn't an available interface to use.
c) Also, if the interface for the tag is in some vendor code that we cannot modify the documentation for, again find a relevant class and add the @service_tag documentation there, with a reference to the interface someone would need to implement if they use this tag.
This is:
#2316857: Handle @service_tag →
We also need a @defgroup that explains what service tags are and how to use them, kind of like what we did for @defgroup annotation. So we should define a @defgroup service_tags in core/modules/system/core.api.php. This was done on:
#2316861: Write a @defgroup for service_tag →
https://www.drupal.org/node/2239393 →
0. Wait for the standard to be adopted. #2745947: Adopt a method of documenting service tags →
1. Create child issues for appropriate groups of tags, ,. We want to have about 5 "document tag" child issues. The list of tags to be documented is on comment #43.
2. Document the new documentation tag @service_tag on https://drupal.org/node/1354
3. Update the handbook: https://www.drupal.org/node/2239393 →
4. Resolve the child issues (make patches).
api.drupal.org will give people documentation of how to use service tags and which ones are available, and there will be cross-linking.
None.
Postponed
11.0 🔥
Enhances developer experience.
Not all content is available!
It's likely this issue predates Contrib.social: some issue and comment data are missing.
@chx just made me notice that 🐛 False positive in twig scanning, with reproducer Fixed is a consequence of this.