migrating hooks doc to doxygen?

classic Classic list List threaded Threaded
18 messages Options
Reply | Threaded
Open this post in threaded view
|

migrating hooks doc to doxygen?

Antoine Musso-3
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
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Tyler Romeo
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 | [hidden email]


On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso <[hidden email]> 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
> [hidden email]
> https://lists.wikimedia.org/mailman/listinfo/wikitech-l
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Brad Jorsch (Anomie)
In reply to this post by Antoine Musso-3
On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso <[hidden email]> 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.

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Chad
On Tue, Jun 4, 2013 at 1:40 PM, Brad Jorsch <[hidden email]> wrote:

> On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso <[hidden email]> 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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Ryan Lane-2
On Tue, Jun 4, 2013 at 1:43 PM, Chad <[hidden email]> wrote:

> On Tue, Jun 4, 2013 at 1:40 PM, Brad Jorsch <[hidden email]> wrote:
> > On Tue, Jun 4, 2013 at 12:00 PM, Antoine Musso <[hidden email]>
> 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
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Antoine Musso-3
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.

--
Antoine "hashar" Musso


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Niklas Laxström
In reply to this post by Antoine Musso-3
On 4 June 2013 19:00, Antoine Musso <[hidden email]> 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/2cd676fd53e4d2dd45ac22972175739f0b3e2bf0/hooks.txt
* https://www.mediawiki.org/wiki/Help:Extension:Translate/Hooks

  -Niklas

--
Niklas Laxström

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Matthew Flaschen-2
In reply to this post by Ryan Lane-2
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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Max Semenik
In reply to this post by Antoine Musso-3
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.


--
Best regards,
  Max Semenik ([[User:MaxSem]])


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Antoine Musso-3
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 :-)


--
Antoine "hashar" Musso


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Antoine Musso-3
In reply to this post by Brad Jorsch (Anomie)
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.


--
Antoine "hashar" Musso


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

S Page-3
In reply to this post by Antoine Musso-3
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 :)

--
=S Page  software engineer on Editor Engagement Experiments
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Daniel Friesen-2
On Sat, 08 Jun 2013 01:09:26 -0700, S Page <[hidden email]> 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.


--
~Daniel Friesen (Dantman, Nadir-Seen-Fire) [http://danielfriesen.name/]


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Raylton P. Sousa
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 <[hidden email]>

> On Sat, 08 Jun 2013 01:09:26 -0700, S Page <[hidden email]> 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
> [hidden email]
> https://lists.wikimedia.org/**mailman/listinfo/wikitech-l<https://lists.wikimedia.org/mailman/listinfo/wikitech-l>
>
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Brian Wolff
>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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Brad Jorsch (Anomie)
On Sat, Jun 8, 2013 at 11:07 AM, Brian Wolff <[hidden email]> 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.


--
Brad Jorsch
Software Engineer
Wikimedia Foundation
_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Antoine Musso-3
In reply to this post by Antoine Musso-3
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 :)

--
Antoine "hashar" Musso


_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Reply | Threaded
Open this post in threaded view
|

Re: migrating hooks doc to doxygen?

Legoktm
In reply to this post by Brad Jorsch (Anomie)
On Sat, Jun 8, 2013 at 8:26 AM, Brad Jorsch <[hidden email]> wrote:
> On Sat, Jun 8, 2013 at 11:07 AM, Brian Wolff <[hidden email]> 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

_______________________________________________
Wikitech-l mailing list
[hidden email]
https://lists.wikimedia.org/mailman/listinfo/wikitech-l