Contrib.social

Adopt a method of documenting service tags

Open on Drupal.org →
Created on 9 June 2016, almost 9 years ago
Updated 20 August 2024, 8 months ago

Problem/Motivation

On Drupal Core issue #2264047: [meta] Document service definition tags → , 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.

Benefits

Developers would know about service tags. As 🐛 False positive in twig scanning, with reproducer Fixed shows some of the most experienced developers in the community do not know them.

Three supporters required

  1. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)
  2. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)
  3. https://www.drupal.org/u/ → {userid} (yyyy-mm-dd they added support)

Proposed changes

Under https://www.drupal.org/docs/develop/standards/php/api-documentation-and-... → add a new section for service tags.

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.

Remaining tasks

  2. Add supporters
  3. Create a Change Record
  4. Review by the Coding Standards Committee
  5. Coding Standards Committee takes action as required
  6. Discussed by the Core Committer Committee, if it impacts Drupal Core
  7. Final review by Coding Standards Committee
  8. Documentation updates
    1. Edit all pages
    2. Publish change record
    3. Remove 'Needs documentation edits' tag
  9. If applicable, create follow-up issues for PHPCS rules/sniffs changes
📌 Task
Status

Active

Component

Coding Standards

Created by

🇺🇸United States jhodgdon Spokane, WA, USA

Live updates comments and jobs are added and updated live.
Sign in to follow issues

Comments & Activities

Not all content is available!

It's likely this issue predates Contrib.social: some issue and comment data are missing.

  • Comment over 1 year ago →
    🇺🇸United States Chris Dart

    I prefer the idea of using the @service_tag that clearly states a class because the api.drupal.org never tells us how to instantiate a service of the given class. Why separate these when services should never be instantiated except by using \Drupal::service();? This results in what is essentially special knowledge--something that is anathema to FOSS software principles. It should be tightly connected to the class being instantiated. When I develop custom modules that have services I always include the instructions for instantiation in the class PHPDocBlock so that it's easy for others on my team to see. While this does create redundancy, that's more of an architectural flaw if anything. (Why not define the service entirely in a docblock?) But that's a debate for another day.

  • Comment 8 months ago →
    🇨🇦Canada Charlie ChX Negyesi 🍁Canada

    Let's get the ball rolling again, I tried to adopt the old IS into the new template.

contrib.social Blog FAQ Discussions
Production build 0.71.5 2024