Talk:MediaWiki Documentation Day 2017/Flow

I have a possible request for this Documentation day:

Updating Manual:Hooks and create the missing hooks pages listed on Manual talk:Hooks. It's not a difficult task, since the hooks themselves are listed in hooks.txt in the MediaWiki source code. It's basically copy pasting with the occasional typo/format fixing. The only difficulty here would be figuring out it which version the hooks was added, since that's not clear from hooks.txt.

Thanks. I've added it to the page. (For anyone else reading this, feel free to add requests directly to the page rather than posting them here.)

As per phab:T157757#3258140 I think this would be a wasted effort. Let's automate it instead.

It'd be great if it were automated, but that still leaves Manual:Hooks, and since we do not know when the automation will be ready, the hook pages will remain undocumented for that time. I'm not sure if that's good...

I'd replace Manual:Hooks with some kind of search tool or gadget, it's already pretty unwieldy. As for the automation, it's one of the top entries of this year's developer wishlist. If you are going to the hackathon, let's talk about it :)

Any kind of search tool that doesn't have to be updated manually would be great anyway. I wish I could attend the hackathon, but that's unfortunately not possible now. Maybe next year?

Roughly:

• fetch the list of pages using Template:MediaWikiHook from the API
• parse the wikitext (or maybe parsoid HTML?), fetch template parameters, store them in a DB
• build an index from the description fields
• put a simple list/filter UI (something like Hay's directory in front

phab:T154715 doesn't seem to be blocked on anything, so perhaps could be done before Friday. Then, it would highlight missing docblocks, which could be written.

Now that Codesniffer v0.8.0 is done, can we use it to identify the documentation holes in core, or is it still too buggy to apply there, e.g. not recognizing @inheritdoc.

There are some issues still, like @inheritdoc like you say, but there's a large number of legit CS violations that will now be highlighted. Fixing any is going to help some way towards getting core up to standard.

I'm not sure what the best approach is: I don't suppose anyone wants to end up with massive patches that do nothing but rejigg comments, because they'll be harder to read. But then, a huge number of tiny patches isn't good either, I guess? Perhaps one file or a small number of files at a time? Or one sniff violation? E.g. fix all "Missing parameter name" violations? Although that's likely to be huge too...

Either doing one sniff at a time or one class at a time would probably work.

Thanks for organizing this! If I wanted to chat with others working on docs on that day, where would I ask questions or share achievements? Only on the wiki page or is there an IRC channel (or something else) you'd recommend to join?