Prospective hook interface files have been uploaded to https://gerrit.wikimedia.org/r/c/mediawiki/core/+/574266 . The method doc comments in those files were based on the information available in docs/hooks.txt. All parameters were type-hinted as ?mixed, this is merely a placeholder for review. So, in each new file:
* Edit the method description, making it into complete sentences in some consistent style.
* When the method description says something about the return value, consider moving it into the `@return` section. The generic descriptions in the auto-generated `@return` can be replaced.
* Replace the ?mixed placeholder with the actual type of the parameter. Usually the parameter description explains the type. If the type is a single class, also add the type as a [[https://www.php.net/manual/en/functions.arguments.php#functions.arguments.type-declaration|type hint]] to the relevant parameter.
* Replace DEPRECATED with `@deprecated` and place it below the main description as is conventional.
In each of the 7 files with `// phpcs:disable Generic.Files.LineLength -- Remove this after doc review`, remove the line and rewrap the doc comments so the line length is less than 100 characters.
This should be done in a separate commit once the hook interfaces are approved and are reasonably unlikely to have further bulk changes.
The idea is that the hook interfaces will become the canonical source of hook documentation. Hooks.txt might be kept around for a few releases to document the legacy pre-HookContainer system, but eventually I imagine it will be deleted.