I noticed that https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Menu!MenuActiveTr... has as its first docblock line:

> Provides the default implementation of the active menu trail service.

There are a few more service classes with this sort of wording:

$ ag "Provides the default"
core/lib/Drupal/Core/Controller/TitleResolver.php
11: * Provides the default implementation of the title resolver interface.

core/lib/Drupal/Core/Menu/LocalActionManager.php
22: * Provides the default local action manager using YML as primary definition.

core/lib/Drupal/Core/Menu/LocalTaskManager.php
25: * Provides the default local task manager using YML as primary definition.

core/lib/Drupal/Core/Menu/MenuActiveTrail.php
11: * Provides the default implementation of the active menu trail service.

core/lib/Drupal/Core/Site/MaintenanceMode.php
10: * Provides the default implementation of the maintenance mode service.

core/lib/Drupal/Core/Theme/ThemeManager.php
13: * Provides the default implementation of a theme manager.

So I am wondering: should we document all service classes like this?

Furthermore, should that line include the service name, so something like this:

> Provides the default implementation of the menu.active_trail service.

Comments

joachim created an issue.

dawehner’s picture

dawehner
Primary language German
CreditAttribution: dawehner at Chapter Three commented

IMHO the documentation of a service class should not document that its a service. Its a pure implementation detail that the service is part of the container.

joachim’s picture

joachim CreditAttribution: joachim commented

> Its a pure implementation detail that the service is part of the container.

I see your point...

But on the other hand, a service class shouldn't ever be called directly but obtained from the container by the service name, and looking at a service class, you can't tell that it's registered as a service.

So documenting that it's a service is the class saying, 'Hey, don't ever call me directly. Use me with the foo.bar service.'

jhodgdon’s picture

jhodgdon
she/her
Primary language English
CreditAttribution: jhodgdon commented

I just want to point out that people using api.drupal.org can already see that a particular class has been declared to be the default class of a service.

For instance:
https://api.drupal.org/api/drupal/core!lib!Drupal!Core!Access!DefaultAcc...
says "1 service uses DefaultAccessCheck", which points you to access_check.default:
https://api.drupal.org/api/drupal/core!core.services.yml/service/access_...

Of course, this does not help someone who is using an IDE and never visits api.drupal.org.

drunken monkey’s picture

drunken monkey
he/him
Primary language German
Location Vienna, Austria
CreditAttribution: drunken monkey as a volunteer commented

Of course, this does not help someone who is using an IDE and never visits api.drupal.org.

PhpStorm (with the Symfony2 plugin) does the same thing – when you view a class, you get a link to the service definition.
So, I'd say this would really be an unnecessary addition.

Chris Dart’s picture

Chris Dart CreditAttribution: Chris Dart at TEN7 commented

An additional problem for new developers especially is this: all services should be instantiated with the \Drupal::service() method. Yet if you go to api.drupal.org to look up a service, nothing in the documentation tells what the name of the service's tag is. Somehow this needs to be documented in one place or the other. I recognize that it creates a redundancy and also may violate a theoretical best practice, but without this easily accessible, instantiating a given service amounts to special knowledge which runs contrary to the spirit accessible open-source software.