I am reporting https://www.drupal.org/coding-standards/docs to moderators because:

In the @file: Documenting files section, there is the following text:

The @file doc block MUST be present for all PHP files, with one exception: files that contain a namespaced class/interface/trait, whose file name is the class name with a .php extension, and whose file path is closely related to the namespace (under PSR-4 or a similar standard), SHOULD NOT have a @file documentation block.

... And that exception seems "wrong".

The argument for having the @file docblock removed is that it's redundant, given that the combination of the file name and file content makes it clear what the file is.

However, the argument for having a @file docblock is that you shouldn't have to look at the file name and examine the file contents in order to determine what the purpose and use case for the file is. Further, NOT have a @file docblock creates an inconsistency in coding conventions that's unnecessary and doesn't actually gain us anything; when we look at the top of the file, we expect the @file docblock to be there, and when it's not there we have to figure out why (i.e. if it's "legitimately" absent or not).

And adding a docblock isn't a great hardship. It's a simple tag that takes only a few seconds to type up -- maybe a minute if one is super careful and thorough about it.

Can we remove this exception please?

Comments

emanaton created an issue. See original summary.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented

The documentation is saying which files must have the directive, and in which files it's not required. As it is, the documentation is correct.

If you are suggesting that all files should have the directive, that is not a change in the documentation, but of the coding standards. As such, that is discussed in a different queue, as far as I remember.

avpaderno’s picture

avpaderno
he/him
Primary language Italian
Location Brescia, 🇮🇹 🇪🇺
commented
Title: Moderation report for API documentation and comment standards » @file should be obligatory for every PHP file
Project: Documentation » Coding Standards
Component: Correction/Clarification » Drupal Core Standards
jhodgdon’s picture

jhodgdon
she/her
Primary language English
commented
Status: Active » Closed (duplicate)
Parent issue: » #2304909: Relax requirement for @file when using OO Class or Interface per file
Related issues: +#2735143: @file doc blocks for test classes with an additional class in the file

This issue was discussed extensively from July 2014 to May 2016, and the consensus was that we should make this exception and disallow @file for files containing just one class in a namespace. You can read the discusson on
#2304909: Relax requirement for @file when using OO Class or Interface per file

I guess if you want to reopen the discussion, you could leave this open, but I think since the decision was so recent, the right thing to do would be just to close this issue as a duplicate.

And I would just point out that, although I wasn't entirely in agreement with the prior decision,... you don't have to look at the *content* of the file to know what class is in it. If you are familiar with the Drupal conventions for locations of namespaced files, all you need is the full path to the filename to deduce what class it contains. For example, file core/modules/config/src/Plugin/Foo/Bar.php must contain the class Bar in namespace \Drupal\config\Plugin\Foo.

See also
#2735143: @file doc blocks for test classes with an additional class in the file

emanaton’s picture

emanaton commented

Fair enough - thanks for the feedback.