Automatically generated developer docs about Hooks

Hi @asmecher,

a year ago, you wrote

“My hope is that we can move a lot of content into automatically-generated documenting tools like Doxygen – I wonder whether something can be done with the hook registry along those lines…”

As far as I can see, Doxygen has no scripting capabilites, so doing that would require extending Doxygen.
A cheaper way to go is probably a home-grown PHP script called at build-time and depositing an HTML file right in the OJS file tree:

  • Postulate a comment string format to be used for HookRegistry::call calls. (E.g. /** Called when thisandthat... */ or so)
  • Decorate each HookRegistry::call statement with such a comment
  • Have the script collect all these call lines along with the comments and source file name
  • Sort the blocks into a reasonable order and collect the multiple comments for the same Hook, if any.
  • Generate a nice HTML page with an index.

Hi @prechelt,

I wonder also about using existing Doxygen features for slightly-other-than-their-intended-uses – see e.g. this proposal for documenting Drupal hooks using the @implements Doxygen tag.

One quirk needing consideration is the programmatically-generated hooks, i.e. ones that aren’t named explicitly in the code but will depend on subclass classnames etc. I’m not sure there’s a good general solution that would comprehensively list them, but we may be able to delimit them somehow as using general terms in the naming if we do use @implements?

Alec Smecher
Public Knowledge Project Team

@asmecher Hi Alec,
considering that the hook calls are mere statements (not method declarations), I wonder whether Doxygen has mechanisms to annotate them even once. It certainly cannot annotate all their dynamic variations separately.

I suggest a very different approach:

  • Add two parameters to HookRegistry::call, namely calledwhen = NULL and is_framework_call = false.
    calledwhen is a string containing the documentation: A characterization of when this hook will be called.
  • Make HookRegistry collect calls to call as follows: If this is the first call for a given hookName/calledwhen pair, record the following tuple:
    • hookName
    • calledwhen
    • function name, file name, and line number from the n-th entry on the call stack, where n=2 for ordinary direct calls (that have a literal for the hookName; is_framework_call = false) and n=3 for calls involving abstraction (that construct the hookName dynamically or receive it as an argument as in; is_framework_call = true).
  • The OJS application could then have an admin page that shows the location and documentation of only those hooks that have already been called in the present run of OJS. The page contains a button for resetting the list. (This is an unusual place for developer documentation, but due to the dynamic nature of the resulting list it may be even more useful than a complete static list.)

Does that make sense?