Page MenuHomePhabricator

replace 537 subpages of Manual:Hooks/ with generated doc
Open, LowPublic

Description

There are hundreds of subpages of Manual:Hooks/ on mediawiki.org. Almost none are localized, and there's a general belief most are out of date. I noticed some missing:

  • ArticleUndeleteLogEntry
  • ContentHandlerForModelID
  • SpecialVersionVersionUrl
  • UpdateUserMailerFormattedPageStatus

Instead we could generate documentation of hooks in core from docs/hooks.txt , which developers are pretty good about updating.

Manual:Hooks also includes some extension hooks.

Event Timeline

Spage raised the priority of this task from to Needs Triage.
Spage updated the task description. (Show Details)
Spage added subscribers: Aklapper, Krinkle, Spage, hashar.

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:

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.

Anomie added a subscriber: Anomie.Jun 3 2015, 7:05 PM

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.

Tgr added a subscriber: Tgr.Jun 3 2015, 7:20 PM

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

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?

Tgr added a subscriber: bd808.Jun 4 2015, 8:31 PM

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.

Krenair added a subscriber: Krenair.Jun 4 2015, 8:50 PM
Restricted Application added a subscriber: StudiesWorld. · View Herald TranscriptFeb 12 2016, 5:49 PM
hashar triaged this task as Low priority.Jul 22 2016, 11:50 AM

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)

hashar removed a subscriber: hashar.Mar 24 2017, 8:01 AM
Krinkle removed a subscriber: Krinkle.
Tgr added a comment.May 3 2019, 8:16 PM
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 hooks.txt and upload it to MediaWiki.org.

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