[policy] Use inline @var documentation for more specific class documentation [#2152037]

Updated: Comment 0

Problem/Motivation

There are a lot of places in core where you as a person has more knowledge about a type of a variable than your static tools/IDE.
PhpDoc/PSR-5 supports to use inline documentation for that usecase, see the following example:

Here is simple example. The mana

    /** @var \Drupal\config_translation\ConfigMapperInterface $mapper */
    $mapper = $this->configMapperManager->createInstance($plugin_id);
    $mapper->populateFromRequest($request);

PRO

Better support for static analyse tools/code refactoring
Better support for api docs, like api.drupal.org
Better autocompletion in IDEs
Better documented code, as it explains better what is going on.

CON

None so far?

Proposed resolution

Remaining tasks

User interface changes

API changes

Comments

Comment #1

moshe weitzman CreditAttribution: moshe weitzman commented 7 December 2013 at 17:44

+1 from me. I don't see a CON either.

Comment #2

tim.plunkett

he/him

English

Philadelphia

CreditAttribution: tim.plunkett commented 7 December 2013 at 18:26

This is already used in HEAD in more than a dozen places, not counting hundreds of usages in Symfony.
+1 for codifying it.

Comment #3

jhodgdon

she/her

English

CreditAttribution: jhodgdon commented 7 December 2013 at 18:50

I do not see a problem with it either.

However, I would just like to point out that I suggested putting /** */ comments inside of hook_element_info() in order to get rid of the Form API reference over on #1617948-14: [policy for now] New standard for documenting form/render elements and properties, and on #19, sun said it was bad (elaborated lower down), and on #28 effulgentsia said it was bad, for two different reasons.

If we are able to do this, can we also go back to the idea of getting rid of the friggin horrible unmaintainable form API reference and put element documentation inside hook_element_info() (which I think we still have for 8, right?)?

Comment #4

fietserwin

Le Mont-Dore

CreditAttribution: fietserwin commented 10 August 2014 at 17:45

+1 on this one as well. The cons mentioned by @sun and @effulgentsia in the other issue are not correct in the first place.

@sun: never ever use multi line comment in function/metgod block: not true, see #2.
@effulgentsia: mass commenting out: Most IDE's support this. E,g. ctrl + / in, at least, PhpStorm and Eclipse, ctrl + Q in notepad++ (not even an IDE, but a text editor).