Hello,
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
I have used that patch to generate a temporary documentation. That lets everyone browse the result easily. The produced result is:
A landing page: https://doc.wikimedia.org/mw-hooks/hooks_mainpage.html
The doc overview: https://doc.wikimedia.org/mw-hooks/page_hooks_documentation.html
A list of hooks with their documentation: https://doc.wikimedia.org/mw-hooks/page_hooks_list.html
I think that makes it a bit more accessible to everyone and Doxygen autolink to referenced classes.
Some issues I have:
- the hooks are listed alphabetically when they could be regrouped by theme (like API, SpecialPages, HTML Forms ...).
- The hooks are documented in a separate file (still docs/hooks.txt), when we might want to have the doc near the wfRunHooks() call.
Thoughts ?
Looks pretty nice. My only complaint is that on the list page the hook header text is the same font size and weight as the "Parameters" header. I know it's indented, so you can sort of tell, but for ease of use purposes I think we should somehow change that.
- The hooks are documented in a separate file (still docs/hooks.txt),
when we might want to have the doc near the wfRunHooks() call.
This would be nice, but it'd have to be possible first. Not sure if Doxygen can even do that. Besides, it'd also mean the maintenance script would have to scan every file rather than just a doc/hooks.txt file.
*-- * *Tyler Romeo* Stevens Institute of Technology, Class of 2016 Major in Computer Science www.whizkidztech.com | [email protected]
On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso [email protected] wrote:
Hello,
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
I have used that patch to generate a temporary documentation. That lets everyone browse the result easily. The produced result is:
A landing page: https://doc.wikimedia.org/mw-hooks/hooks_mainpage.html
The doc overview: https://doc.wikimedia.org/mw-hooks/page_hooks_documentation.html
A list of hooks with their documentation: https://doc.wikimedia.org/mw-hooks/page_hooks_list.html
I think that makes it a bit more accessible to everyone and Doxygen autolink to referenced classes.
Some issues I have:
- the hooks are listed alphabetically when they could be regrouped by
theme (like API, SpecialPages, HTML Forms ...).
- The hooks are documented in a separate file (still docs/hooks.txt),
when we might want to have the doc near the wfRunHooks() call.
Thoughts ?
-- Antoine "hashar" Musso
Wikitech-l mailing list [email protected] https://lists.wikimedia.org/mailman/listinfo/wikitech-l
On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso [email protected] wrote:
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
The result is pretty. But personally I'll probably continue to just look in hooks.txt if I need the info in there, and the markup in the (now-misnamed) file is rather ugly. Not that the existing file isn't also ugly, just less so.
On Tue, Jun 4, 2013 at 1:40 PM, Brad Jorsch [email protected] wrote:
On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso [email protected] wrote:
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
The result is pretty. But personally I'll probably continue to just look in hooks.txt if I need the info in there, and the markup in the (now-misnamed) file is rather ugly. Not that the existing file isn't also ugly, just less so.
I'm with Brad. Considering we document this in the tree and on mw.org, I'm not entirely sure what the benefit of having it done via Doxygen is.
-Chad
On Tue, Jun 4, 2013 at 1:43 PM, Chad [email protected] wrote:
On Tue, Jun 4, 2013 at 1:40 PM, Brad Jorsch [email protected] wrote:
On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso [email protected]
wrote:
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
The result is pretty. But personally I'll probably continue to just look in hooks.txt if I need the info in there, and the markup in the (now-misnamed) file is rather ugly. Not that the existing file isn't also ugly, just less so.
I'm with Brad. Considering we document this in the tree and on mw.org, I'm not entirely sure what the benefit of having it done via Doxygen is.
I've never understood why we have some subsection of documentation stuck in the tree. It makes no sense. If we want to include docs with the software shouldn't we just dump tagged docs from mediawiki.org into the tree, per release? Right now we have docs in two places to keep up to date and neither place is kept very well documented.
- Ryan
Le 04/06/13 20:03, Ryan Lane a écrit :
I've never understood why we have some subsection of documentation stuck in the tree. It makes no sense. If we want to include docs with the software shouldn't we just dump tagged docs from mediawiki.org into the tree, per release? Right now we have docs in two places to keep up to date and neither place is kept very well documented.
I would myself drop the mediawiki.org documentation in favour of inline documentation which is thus kept in sync with the code. I barely update the mw.org doc when doing changes.
On 04.06.2013, 22:33 Antoine wrote:
I would myself drop the mediawiki.org documentation in favour of inline documentation which is thus kept in sync with the code. I barely update the mw.org doc when doing changes.
How large inline documentation can be? The benefit of a wiki is that you can have large pages with a lot of documentation, examples and _links_ - not something you can do in a comment.
Le 05/06/13 16:59, Max Semenik a écrit :
How large inline documentation can be? The benefit of a wiki is that you can have large pages with a lot of documentation, examples and _links_ - not something you can do in a comment.
Doxygen has support for examples, you could even get them out of the code and refer to them or include them.
Same for links, methods are already autolinked, but one could create references and link to them using @ref :-)
On 06/04/2013 02:03 PM, Ryan Lane wrote:
I've never understood why we have some subsection of documentation stuck in the tree. It makes no sense. If we want to include docs with the software shouldn't we just dump tagged docs from mediawiki.org into the tree, per release? Right now we have docs in two places to keep up to date and neither place is kept very well documented.
I agree, it's a pain to have in both places. But I think the single place should be the source. Then, you can check that the change includes a doc update before +2'ing.
It would be better to generate mediawiki.org hook docs from the source, in my opinion.
Matt Flaschen
Le 04/06/13 19:40, Brad Jorsch a écrit :
The result is pretty. But personally I'll probably continue to just look in hooks.txt if I need the info in there, and the markup in the (now-misnamed) file is rather ugly. Not that the existing file isn't also ugly, just less so.
An interesting Doxygen feature is the ability to generate man pages. One could add in its MANPATH $IP/docs/man and then do something like man 3 page_hooks_list . That shows up a nicely formatted list of hooks.
You can give it a try with:
git-review -d 66128 php maintenance/mwdocgen.php --generate-man --file=docs/hooks.txt man man docs/man/man3/page_hooks_list.3
Should probably make the section named mw-hooks-list or something :)
Example:
Language* Language::getMessagesFileName Parameters: $code The language code or the language we are looking for a messages file for &$file The messages file path, you can override this to change the location.
On 4 June 2013 19:00, Antoine Musso [email protected] wrote:
Hello, Thoughts ?
I had taken another approach in Translate which was designed to be easy to sync to wiki: * https://git.wikimedia.org/blob/mediawiki%2Fextensions%2FTranslate.git/2cd676... * https://www.mediawiki.org/wiki/Help:Extension:Translate/Hooks
-Niklas
-- Niklas Laxström
This is great. I think building HTML from source files is the way to go for dry reference material like this.
You need links both ways so people know the other format is available. The hooks.txt should say "The documentation at https://doc.wikimedia.org/mw-hooks/hooks_mainpage.htmlis regularly generated from the master branch of the gerrit repository."
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. 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.
- 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.
Now that we have mw.hook() in JavaScript we have a second universe of hooks to think about :)
On Sat, 08 Jun 2013 01:09:26 -0700, S Page [email protected] 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... ;) 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.
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 [email protected]
On Sat, 08 Jun 2013 01:09:26 -0700, S Page [email protected] 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 [email protected] https://lists.wikimedia.org/**mailman/listinfo/wikitech-lhttps://lists.wikimedia.org/mailman/listinfo/wikitech-l
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.
I agree 100%. It would be cool if we had a bot auto-update part of those page (While still allowing users to add info and tips). Maybe even some sort of parser function to retrieve documentation...
Both Manual:Hooks/foo and all the $wgFoo pages can definitely benefit from some automation. (Even cooler, would be if we could have something like Special:Documentation/Linker::link (Before anyone balks, :: is allowed in special page subpage name), which retrieved the info from doxygen for that page, as an alternative way to view the docs).
--bawolff
On Sat, Jun 8, 2013 at 11:07 AM, Brian Wolff [email protected] wrote:
Both Manual:Hooks/foo and all the $wgFoo pages can definitely benefit from some automation.
I know the reason I usually don't update the Manual pages is because by the time the change gets reviewed and merged, I don't remember anymore that the change actually requires Manual page updates. I have the same problem with remembering to close bugs; the automated comments posted to the bug on merge now often remind me, at least for bugs I'm on the CC list for.
If someone were to write a bot that would comment on the changeset after it was merged linking to hook and $wgFoo manual pages that probably need updating, that would serve as a useful reminder.
On Sat, Jun 8, 2013 at 8:26 AM, Brad Jorsch [email protected] wrote:
On Sat, Jun 8, 2013 at 11:07 AM, Brian Wolff [email protected] wrote:
Both Manual:Hooks/foo and all the $wgFoo pages can definitely benefit from some automation.
I know the reason I usually don't update the Manual pages is because by the time the change gets reviewed and merged, I don't remember anymore that the change actually requires Manual page updates. I have the same problem with remembering to close bugs; the automated comments posted to the bug on merge now often remind me, at least for bugs I'm on the CC list for.
A bit late, but I wrote a script[1] to do this today, since I didn't want to manually create a page for the hook I added to core today[2].
It's not totally perfect, [3] doesn't look that nice, and it's not smart enough to figure out things like the type of an object based on reading the text.
If someone were to write a bot that would comment on the changeset after it was merged linking to hook and $wgFoo manual pages that probably need updating, that would serve as a useful reminder.
If people like this script, we could have a bot automatically create a stub page on mw.o when the change is merged, and then a human can fix it up.
-- Legoktm
[1] https://github.com/legoktm/mwhooks/blob/master/create_onwiki.py [2] https://www.mediawiki.org/wiki/Manual:Hooks/GetLogTypesOnUser [3] https://www.mediawiki.org/wiki/Manual:Hooks/WikiPageDeletionUpdates
Le 04/06/13 18:00, Antoine Musso a écrit :
Hello,
Since we introduced hooks in MediaWiki, the documentation has been maintained in a flat file /docs/hooks.txt . Over the week-end I have converted the content of that file to let Doxygen recognize it.
The patchset is: https://gerrit.wikimedia.org/r/#/c/66128/
<snip>
After two weeks, it seems the single objection against converting the plain text to Doxygen format is the markup format when reading the flat file. On the other hands a few people like the HTML output and some people praised this change either over IRC or by private mail.
Regardless of where we should maintain the doc, is there anything preventing the change to land in? Please cast your voice :)