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 that start with either: “Use this hook to…” or “This hook is called [when/after/etc]…”
- 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 DEPRECATED with @deprecated and place it in the interface doc block in place of @stable.
- Replace the ?mixed placeholder with the actual type of the parameter. Usually the parameter description explains the type.
- Edit the parameter description, making it start with a capital letter
- If a parameter takes an object as the type, use the object name as the type hint, add a “Use…” statement to the file, and remove the description if it’s redundant with the type hint. For example: @param ?mixed $user User object can be changed to @param User $user.
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.