I've used (and use) doxygen+txt+mediawiki and was very helpful(still include myself in new dev).
But, on the other hand, in the hooks (without doxygen), I always had trouble knowing when and where it is loaded. And it is always hard to figure out which one to use.
Probably a newbie problem, but since we are talking about this. I decided to say.
2013/6/8 Daniel Friesen daniel@nadir-seen-fire.com
On Sat, 08 Jun 2013 01:09:26 -0700, S Page spage@wikimedia.org wrote:
If mediawiki.org's extension template linked "hooks in use" to this doc
instead of mediawiki.org/Hooks:xyz pages then we could retire the latter pages and have less stuff to maintain.
MediaWiki.org doesn't have //mediawiki.org/Hooks:xyz pages, it has // mediawiki.org/wiki/Manual:**Hooks/xyz.http://mediawiki.org/wiki/Manual:Hooks/xyz... ;) but I wouldn't be opposed to creating a dedicated / mediawiki.org/wiki/Hook:xyz namespace.
Except...
- It's sometimes useful that the Hooks pages are searchable along with the
rest of the documentation on mediawiki.org.
- The mw.org hooks pages have additional information. E.g. comparing
https://doc.wikimedia.org/mw-**hooks/page_hooks_list.html#** UserCreateFormhttps://doc.wikimedia.org/mw-hooks/page_hooks_list.html#UserCreateFormand http://www.mediawiki.org/wiki/**Manual:Hooks/UserCreateFormhttp://www.mediawiki.org/wiki/Manual:Hooks/UserCreateForm, the mw.org page has ** version = 1.6.0 ** source = SpecialUserlogin.php ** These categorize it as [Hooks added in MediaWiki 1.6.0] and [MediaWiki hooks included in SpecialUserlogin.php]
If we add this information to hooks.txt maybe there's a way doxygen can show the information and produce tables similar to the categories.
There are other things the hooks pages have that hooks.txt doesn't and may never:
- Some of them have extra documentation and more details than what we can
simply fit into hooks.txt: https://www.mediawiki.org/** wiki/Manual:Hooks/PersonalUrlshttps://www.mediawiki.org/wiki/Manual:Hooks/PersonalUrls
- Hooks pages document all hooks past and present with information on when
hooks are removed and references to their replacements. Auto-generated hooks documentation however generally just makes said hook documentation disappear when we naturally remove it from the software.
To be clear I'm not really in favor of moving more things to our doxygen setup. Quite frankly I haven't met a single person who's said they actually used the Doxygen documentation. Most new devs likely don't even know it exists. And I'd bet many core devs are just like me and instead of opening up Doxygen we just quickly open the relevant php file and read the documentation comment raw.
I find the Doxygen documentation to be hard to navigate, slow, and extremely disorganized. I also do not expect the visual disconnect of leaving the MediaWiki.org site and the MW UI and then landing on Doxygen's own custom style will be helpful at all to the user. The search bar is so recluse-ly tucked away that I've never attempted using it. And as expected typing "User" into it wasn't very helpful at all.
The hooks pages on the other hand. Even I've used once or twice. And I'll admit I've had to fix some and felt others needed work. But automating away from them is probably the wrong way to do things.
Frankly I think we should try automating stuff towards our wiki rather than using it as a way to take stuff out. Find ways to integrate this data automatically into parts of the wiki. Bots if you ABSOLUTELY need to. But preferably instead extensions and Lua stuff. Things that provide the data in ways they can be incorporated into wiki pages. Keep wiki pages up to date. Show full UIs, etc... on special pages and dedicated namespaces. And ideally, be integrated right into the search.
Speaking of search there's something that's been bothering be for awhile. The Extension:, Skin:, and API: namespaces aren't part of our default search namespaces. A chunk of information about the stuff people come to the wiki for isn't even easily searchable.
- The hooks are documented in a separate file (still docs/hooks.txt),
when we might want to have the doc near the wfRunHooks() call.
Hmm. On the one hand if they're all in one place it's easier to do cargo-cult pattern matching when adding new hook documentation. But if the doc is in the PHP near the wfRunHooks call it's more likely people will update it when making changes.
Hooks can be run from more than one location. I know the skin system has a few of those and I wouldn't be surprised if this was true of other parts of core and extensions even too. They are also run inline where a lot of other code is going on. Breaking that complicated method flow with a huge hook documentation comment really doesn't sound like a good idea.
So I don't think inline hook documentation is a good idea, it's best to stick with a common location.
-- ~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/]
______________________________**_________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/**mailman/listinfo/wikitech-lhttps://lists.wikimedia.org/mailman/listinfo/wikitech-l