On Sat, 08 Jun 2013 01:09:26 -0700, S Page <spage(a)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.
doesn't have //mediawiki.org/Hooks:xyz pages, it has
//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
and
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
* 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/]