API-docs support for OO hooks implementations in classes

Migrated issue

Reported by: joachim

Related to !45 (merged)

Problem/Motivation

#3442009: OOP hooks using attributes and event dispatcher allows marking class methods and classes with the #[Hook] attribute to implement a hook. See the change record for more. api needs to support this.

Steps to reproduce

Proposed resolution

  1. Add attribute parsing on class methods to Parser. This issue is limited to parsing #[Hook('foo')] to mean the same as Implements hook_foo()..
  2. Store these somehow. I have chosen separate docblocks with an object_type of hook. As one method can implement multiple hooks it is necessary to have multiple docblocks. These are essentially proxy records, the real doxygen, code et al live in their parent method docblock and hook docblocks are never displayed. ExtendedQueries::findReferences resolves this proxy.
  3. Add the implements hook_foo(). to Formatter::pageFunction for each hook docblock. A bit of a lie but currently we do not have a better way to link back to the hook documentation.

It speaks very highly of the current api module codebase how easy all this is.

Remaining tasks

  1. Support class #[Hook] as well. Quite a bit harder as we need to parse the argument method: / fall back to method being __invoke.
  2. Add constant expression evaluation to Parser preferably with full constant resolution, after all constants are picked up by api already.
  3. Wherever core moves the doxygen from foo.api.php we will need to support that.

User interface changes

API changes

Data model changes

Related issue: Issue #3442009

Edited by drupalbot