Make @file optional for *.module and *.install files

I agree that for seasoned Drupal developers these docblocks are redundant, but it still makes sense for junior developers, or developers coming from other platforms to provide context. I can imagine a Symfony developer that is doing a Drupal 8 project being confused by these weird ".module" and ".install" file extensions. It are exactly these files that contain our odd hook-based drupalisms, and a single line of documentation goes a long way to inform people what this is all about.

The examples you provide are noteworthy. I don't mind the standard pattern used for aggregator.install, but ban.module should be better along the lines of

/**
 * @file
 * Main functions and hook implementations of the Ban module.
 */

And "Miscellaneous functions" is just sad.

@pfrenssen Good point about information for newcomers!
I wonder though if this is really worth the trouble. It is a trade-off.

I see similar arguments apply here like for "convention over configuration".

A lot of organisations will ask their developers to follow the standards from https://www.drupal.org/docs/develop/standards/api-documentation-and-comm... to the letter for custom code.

It could be useful to suggest that organisations or contrib developers can opt out of specific rules.
Of course no organisation is forced to follow anything, but it can be suggested which rules are absolutely recommended and which could be considered optional.

The main argument provided for @file docs is that they will be read by the API module. Typically this is irrelevant for custom code.

On the other hand, @param and @return docs can be read by an IDE and are very useful.

@pfrenssen to add to my previous comment.

I agree that for seasoned Drupal developers these docblocks are redundant, but it still makes sense for junior developers, or developers coming from other platforms to provide context.

This is a nice intention, but it is not what I see being done in custom modules for real-world website projects.
Instead, I see people run phpcbf to insert stub comments, and then (if we are lucky) these stubs are filled out with random meaningless phrases.
All of this is done for compliance, not to make the code more readable.

For developers who care more, there is a risk of losing valuable time, billed to the client or employer, to bikeshed which phrase to use in this doc block.

(My personal philosophy is "If you don't have something meaningful to say, don't say it.". But this goes beyond this issue.)

Another risk is that developers are too specific in the @file doc, e.g.

/**
 * @file
 * The *.module file which contains hook_menu(), hook_block_info() and hook_block_view().
 */

A doc phrase like this either will get outdated very soon, or it has to be updated whenever something new is added to the file.

Something more generic like "This is the place for hook_menu(), hook_block_info() or other hooks." can avoid this. But does every developer you add to a project know this?

Another anti-pattern is to use the @file doc to explain what the module does.
E.g. in D7 node.module:

/**
 * @file
 * The core that allows content to be submitted to the site. Modules and
 * scripts may programmatically submit nodes using the usual form API pattern.
 */

This text has nothing to do with the *.module file specifically, it rather belongs into a README, or into the description in the *.info file.
Or optionally it could go into a section into the @file doc, but below the top line which should document the role of this specific file, not the role of the module itself.

It are exactly these files that contain our odd hook-based drupalisms, and a single line of documentation goes a long way to inform people what this is all about.

The goal you mention could be achieved with a standardized phrase, e.g.

/**
 * @file
 * Main *.module file which will be included on every page request.
 */

/**
 * @file
 * The modules's *.install file.
 *
 * This file is only included when the module is installed, uninstalled or
 * updated, and some other cases. It is the place for hook_install(),
 * hook_uninstall(), hook_update_N() and hook_schema().
 */

Such default docs could be inserted automatically by a tool like phpcbf, which would reduce the risk that developers insert useless comments only for the sake of compliance.

Still this is not a guarantee that developers will use these standardized phrases, or that they will insert anything useful at all instead of meaningless or even misleading text.

I agree that for seasoned Drupal developers these docblocks are redundant, but it still makes sense for junior developers, or developers coming from other platforms to provide context. I can imagine a Symfony developer that is doing a Drupal 8 project being confused by these weird ".module" and ".install" file extensions. It are exactly these files that contain our odd hook-based drupalisms, and a single line of documentation goes a long way to inform people what this is all about.

With the current way core seems to be going in trying to remove most of these files, by making hooks annotation based, it looks like the argument is start to lose value?

There are only 86 .module files left, so this is mostly about .install files. I am not a fan of the extra documentation in the example for .install in #6. If we wanted to do something like that I would rather it just be @see to other API documentation.