Problem/Motivation
api.drupal.org currently links Implements hook_form_FORM_ID_alter to function hook_form_FORM_ID_alter where the doxygen lives. In order to be able to link #[FormAlter('filter_admin_overview')] to the documentation page, this attribute introduced PREFIX and SUFFIX constants.
However, the implementation to this created multiple WTF moments where $hook became optional and by dropping the constructor from classes extending Hook now the first argument of FormAlter is called $hook instead of a friendly $form_id
Steps to reproduce
n/a
Proposed resolution
Introduce an attribute which shows which hook documentation should be linked when the attribute is used:
#[HookDocumentation('hook_form_alter')]
#[HookDocumentation('hook_form_FORM_ID_alter')]
#[HookDocumentation('hook_form_BASE_FORM_ID_alter')]
class FormAlter {
This was originally not chosen for FormAlter because of a misplaced fear that this attribute will not be used properly vs the implementation forcing correctness but then again currently one needs to properly use doxygen per implementation in order for documentation linking to work and so one per definition is certainly much easier.
Also, much as the current doxygen per implementation only works in a specific format "Implements hook_foo()", this new attribute should document to only use string literals as the value of prefix and suffix -- PHP allows for all sort of wild constant expressions, these won't be supported. This, once again, is not an arduous requirement. (It's why I do not want to ask people to put the entire regular expression here just the hook string: asking for a preg would be arduous and error prone and conversion is easy.)