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 <dan...@nadir-seen-fire.com> > On Sat, 08 Jun 2013 01:09:26 -0700, S Page <sp...@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#** >> UserCreateForm<https://doc.wikimedia.org/mw-hooks/page_hooks_list.html#UserCreateForm>and >> http://www.mediawiki.org/wiki/**Manual:Hooks/UserCreateForm<http://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/PersonalUrls<https://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-l<https://lists.wikimedia.org/mailman/listinfo/wikitech-l> > _______________________________________________ Wikitech-l mailing list Wikitech-l@lists.wikimedia.org https://lists.wikimedia.org/mailman/listinfo/wikitech-l
