For the vast majority of PHP files that only define a class, the @file annotation does not appear to be useful.

In fact, it actively clutters Doxygen's index with duplicate file-based entries that are less useful than their class-based counterparts.

Example: filerepo

Group menu	File page	Class page

I imagine one would only visit the File page by mistake, leading to a mostly empty page with 1 significant link, that brings you to the class page.

Below an example of a group that doesn't do this (these class files do actually have @file but without @ingroup on those, thus emulating the same outcome as if they didn't have @file).

Group menu (no @file duplicates)

Note that for the purposes of the File browser, @file is not considered. The File browser in Doxygen shows all files no matter what. For example, includes/ReadOnly.php has no @file comment currently in master, but it's file is still known in the browser:

In summary

The only purpose of @file is to create a dedicated menu item in Doxygen outside the file browser, about a file. This is mainly useful as a way to document a file that does something other than define a class (which would already get its own menu item).

For example, a file like DefaultSettings.php or GlobalFunctions.php can be useful to add to the menu so that its variables/functions can be navigated to from the module browser (given that variables and functions are usually not placed in a Doxygen group directly).

For those files, the @file is to the variables and functions, what @class is to class members and methods. A container for documentable entities that we wouldn't put @ingroup on directly.

Relevant conventions doc: Manual:Coding_conventions

Progress for areas more or less the CPT and Perf team scopes:

• API
• Database
• ExternalStorage
• Entry points
• File backend
• FileRepo
• Installer
• ObjectStore (libs/objectcache)
• Profiler
• Redis
• ResourceLoader
• …