Mailing List Archive

Generating documentation from JavaScript doc comments
We have all these JavaScript documentation comments, but we're not
actually generating docs. This has been talked about before, e.g.
http://www.gossamer-threads.com/lists/wiki/wikitech/208357?do=post_view_threaded,
https://bugzilla.wikimedia.org/show_bug.cgi?id=40143,
https://www.mediawiki.org/wiki/Requests_for_comment/Documentation_overhaul#Implementation_ideas
.

I don't think Doxygen is the best choice, though. JavaScript is really
put forth as a sort-of afterthought.

I suggest JSDoc (http://usejsdoc.org/), simply because it's a standard
library and has has been put forward in the past, with good rationale.

I know there are other good ones too.

What do you think?

Matt Flaschen

_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: Generating documentation from JavaScript doc comments [ In reply to ]
On Dec 28, 2012, at 5:05 AM, Matthew Flaschen <mflaschen@wikimedia.org> wrote:

> We have all these JavaScript documentation comments, but we're not
> actually generating docs. This has been talked about before, e.g.
> http://www.gossamer-threads.com/lists/wiki/wikitech/208357?do=post_view_threaded,
> https://bugzilla.wikimedia.org/show_bug.cgi?id=40143,
> https://www.mediawiki.org/wiki/Requests_for_comment/Documentation_overhaul#Implementation_ideas
> .
>
> I don't think Doxygen is the best choice, though. JavaScript is really
> put forth as a sort-of afterthought.
>
> I suggest JSDoc (http://usejsdoc.org/), simply because it's a standard
> library and has has been put forward in the past, with good rationale.
>
> I know there are other good ones too.
>
> What do you think?
>
> Matt Flaschen

Doxygen is indeed not meant for JavaScript. With some hacks it can be tricked into reading comment blocks from javascript files, but that won't scale for our code base, nor will it be enough to make a useful structure given the dynamic way JavaScript works.

JSDoc is pretty solid, though there are some concerns:
* The syntax is somewhat foreign compared to what we're doing right now
* Development is unclear (v2 on google-code has been discontinued, v3 on github is a rewrite still being worked on)
* Written in javascript, but doesn't run on node. Requires Java.
* Features appear to cover the general cross-language cases, but too limited when trying to document more complex javascript solutions (e.g. VisualEditor's code base).

I've recently looked into a documentation generator for VisualEditor and though I haven't stopped looking yet, I'm currently pausing rather long at JSDuck. It is very well engineered and especially optimised for modern JavaScript (inheritance, mixins, event emitters, override/overload methods from another module, modules, etc.).

It is also easy to extend when needing to implement custom @tags.

I've set up a vanilla install for VisualEditor's code base here:

http://integration.wmflabs.org/mwext-VisualEditor-docs/

Right now, like MediaWiki core, VisualEditor is just documenting code loosely, not following any particular doc-syntax, so we're bound to require a few tweaks[1] no matter which framework we choose. Our current syntax is just something we came up with loosely based on what we're used to with Doxygen.

Right the demo on labs only uses the "Doc" app of JSDuck, but it also supports Guides, Demo's, interactive live-editable Examples and more.

A few random things I like in particular about JSDuck are:
* Support documenting parameters of callback functions
* Support documenting events emitted by a class/module
* Option to show/hide inherited methods and other characteristics
* Support to completely document objects for @param and @return (like @param {Object} foo, @param {number} foo.bar)
* Live search and permalinks
* Markdown all the way + duck extension for doc specific syntax (e.g. @link and #method)

If it works out, I think we can get this going for MediaWiki core as well.

Regardless of the framework we choose, we should set it up to be generated for branches and update on merge from jenkins's post-merge hooks. Come to think of it, we should probably do that for the PHP/Doxygen as well (is that still running from the cronjob on svn.wikimedia.org?).

-- Krinkle

[1] Perfectionist alert, this commit does more than just the necessary "tweaks": https://gerrit.wikimedia.org/r/42221/


_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: Generating documentation from JavaScript doc comments [ In reply to ]
On 01/04/2013 08:00 AM, Krinkle wrote:
> Doxygen is indeed not meant for JavaScript. With some hacks it can be tricked into reading comment blocks from javascript files, but that won't scale for our code base, nor will it be enough to make a useful structure given the dynamic way JavaScript works.
>
> JSDoc is pretty solid, though there are some concerns:
> * The syntax is somewhat foreign compared to what we're doing right now
> * Development is unclear (v2 on google-code has been discontinued, v3 on github is a rewrite still being worked on)
> * Written in javascript, but doesn't run on node. Requires Java.

One that does run on node is YUIDoc. I'm using an older version
successfully for ProveIt, and hopefully it has improved since then.
http://yui.github.com/yuidoc/

> I've recently looked into a documentation generator for VisualEditor and though I haven't stopped looking yet, I'm currently pausing rather long at JSDuck. It is very well engineered and especially optimised for modern JavaScript (inheritance, mixins, event emitters, override/overload methods from another module, modules, etc.).

How do you do modules? I don't see @module at
https://github.com/senchalabs/jsduck/wiki/Guide . JSDoc
(http://usejsdoc.org/#JSDoc3_Tag_Dictionary) and YUIDoc
(http://yui.github.com/yuidoc/syntax/index.html) both have them.

I think the module concept is important, since we have so many, and many
(e.g. the API ones) just modify existing classes.

> It is also easy to extend when needing to implement custom @tags.

That's good, and we could use it to implement module.

> I've set up a vanilla install for VisualEditor's code base here:
>
> http://integration.wmflabs.org/mwext-VisualEditor-docs/

The docs definitely look great. I like (among other things) that they
link to docs for the native types.

> Right now, like MediaWiki core, VisualEditor is just documenting code loosely, not following any particular doc-syntax, so we're bound to require a few tweaks[1] no matter which framework we choose. Our current syntax is just something we came up with loosely based on what we're used to with Doxygen.

Right, we're going to have to change stuff either way, so the important
thing is choosing something solid.

> Right the demo on labs only uses the "Doc" app of JSDuck, but it also supports Guides, Demo's, interactive live-editable Examples and more.
>
> A few random things I like in particular about JSDuck are:
> * Support documenting parameters of callback functions
> * Support documenting events emitted by a class/module
> * Option to show/hide inherited methods and other characteristics
> * Support to completely document objects for @param and @return (like @param {Object} foo, @param {number} foo.bar)

Those do sound pretty cool.

> If it works out, I think we can get this going for MediaWiki core as well.

Great. I was thinking we could start with a Labs install just to see
how it looks initially.

> Regardless of the framework we choose, we should set it up to be generated for branches and update on merge from jenkins's post-merge hooks. Come to think of it, we should probably do that for the PHP/Doxygen as well (is that still running from the cronjob on svn.wikimedia.org?).

Agreed, auto-updating docs on merge would be nice.

Matt Flaschen

_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: Generating documentation from JavaScript doc comments [ In reply to ]
Le 04/01/13 14:00, Krinkle a écrit :
> Regardless of the framework we choose, we should set it up to be
> generated for branches and update on merge from jenkins's post-merge
> hooks. Come to think of it, we should probably do that for the
> PHP/Doxygen as well (is that still running from the cronjob on
> svn.wikimedia.org?).

Indeed, the documentation generation is still being made on the server
that host our subversion repositories. It is run once per day from master.

I have already looked at having doc generated for master and release
branches as a post merge commit. I had some bug in Zuul that prevented
me from having the doc properly generated, will have a look at it again
as time allow.

--
Antoine "hashar" Musso


_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: Generating documentation from JavaScript doc comments [ In reply to ]
On Fri, Jan 4, 2013 at 11:00 AM, Krinkle <krinklemail@gmail.com> wrote:
(...)
> I've recently looked into a documentation generator for VisualEditor and though I haven't stopped looking yet, I'm currently pausing rather long at JSDuck. It is very well engineered and especially optimised for modern JavaScript (inheritance, mixins, event emitters, override/overload methods from another module, modules, etc.).
>
> It is also easy to extend when needing to implement custom @tags.
>
> I've set up a vanilla install for VisualEditor's code base here:
>
> http://integration.wmflabs.org/mwext-VisualEditor-docs/

Would it be possible/difficult to get something similar working for
gadgets on WMF wikis?

Helder

_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l
Re: Generating documentation from JavaScript doc comments [ In reply to ]
> Would it be possible/difficult to get something similar working for
> gadgets on WMF wikis?
>
> Helder

What would be really cool would be if the js content handler code detected
code doc comments and formatted them nicely. Something similar to how back
in the old days people used to have things like
/*
==header ==
*/
That would be picked up by mw and formatted as headers. But automatic and
more complete.

-bawolff
_______________________________________________
Wikitech-l mailing list
Wikitech-l@lists.wikimedia.org
https://lists.wikimedia.org/mailman/listinfo/wikitech-l