https://github.com/legoktm/mwhooks could successfully parse docs/hooks.txt and create properly formatted on-wiki pages, but I never got around to finishing it.

@hashar wrote a patch to create hook documentation in doxygen from docs/hooks.txt, gerrit 66128 (screenshot F99738 below). There was some resistance from people in the wikitech-l thread (e.g. here) and people proposed interesting alternatives in the thread, but the current situation seems untenable.

There are many other approaches:

• simply link to docs/hooks.txt in git
• treat it as markdown (sample)
• treat docs/hooks.txt as wikitext and stick that on a wiki using T91626: Technology to transclude git content into wiki pages. Here is the current docs/hooks.txt dumped on a wiki.
• do some pre-processing like doxygen to improve display or split it up
• @Krinkle proposed Special:DocBrowser/Hooks?prefix=Parser in his documentation overhaul RFC.

Here's a screenshot of the doxygen output from hashar's patch:

Thanks @Spage . We could go even one step further and phase out docs/hooks.txt in favor of documenting the hooks on the function that is invoking them. Will have to find a way to gather all such hooks at a central place though which I haven't found how to do with Doxygen.

In T93043#1127863, @hashar wrote:

We could go even one step further and phase out docs/hooks.txt in favor of documenting the hooks on the function that is invoking them.

That assumes there is only one place invoking each hook, though. Or that we make wrapper "callFooHook()" functions when a hook is called from more than one place.

There is a fair amount of extra information on the wiki pages, such as a link to the commit which added the hook (can be very useful when trying to figure out what it is intended for). Replacing hooks.txt with some kind of @hook docblock would certainly be nice, but I'm not sure you can use phpdoc that way.

wiki pages can contain (and some of them do) examples of usage of such hooks. See for example SkinBuildSidebar but I'm sure there are others too

In T93043#1335183, @Ciencia_Al_Poder wrote:

wiki pages can contain (and some of them do) examples of usage of such hooks. See for example SkinBuildSidebar but I'm sure there are others too

Sure, there's always some page that for a while has great additional documentation. But what percentage of the 537 do? That exception doesn't disprove the thesis that doc in source code gets updated, while doc on-wiki is hit-or-miss. We can instead put additional doc in source code (including usage examples), and we can consider some wiki pages for particularly valuable commentary.

It's good if we can provide automatic documentation on wiki pages. But I'd like to also have the ability to expand such pages with examples without the need to submit changes to gerrit.

Maybe a bot could periodically read from docs and update those pages, while leaving a section of the page for additions?

Just talked about this with @bd808 recently. hooks.txt could be migrated to YAML; that's still readable (arguable more readable), close enough that the conversion could be easily scripted, and structured enough that a bot could use it to create the hook pages and update the template values if needed, without destroying any existing information on the wiki pages. Probably adding version numbers / commit ids / deprecation versions for future hooks could be scripted as well.

This should also be versioned, so you can view all the hooks "as of 1.27", "as of 1.28", etc. This is necessary since they change significantly (new/removed arguments, changing deprecations, etc.)

We already do this for Doxygen, and it's standard practice (e.g. Puppet)

In T93043#1338762, @Tgr wrote:

Just talked about this with @bd808 recently. hooks.txt could be migrated to YAML; that's still readable (arguable more readable), close enough that the conversion could be easily scripted, and structured enough that a bot could use it to create the hook pages and update the template values if needed, without destroying any existing information on the wiki pages. Probably adding version numbers / commit ids / deprecation versions for future hooks could be scripted as well.

Brian has a bot for uploading code information to mediawiki.org which could as well be used for this. Filed T222477: Parse MediaWiki hook documentation from hook interfaces and upload it to MediaWiki.org.

Heads-up to @EvanProdromou as this is a developer documentation related area with interesting "duplication"