Page MenuHomePhabricator

Auto-generated gadget code documentation
Open, LowPublic


I believe gadget developers would benefit from having autogenerated code documentation. For example, using JSDuck, as we currently have for various Wikimedia code repositories (MediaWiki core, extensions, libraries).

See also:

See Also:



Event Timeline

bzimport raised the priority of this task from to Low.Nov 22 2014, 1:48 AM
bzimport set Reference to bz51651.
bzimport added a subscriber: Unknown Object (MLST).

I don't see a straight forward path that will enable this within reasonable time for production. jsduck as it is wouldn't integrate very well nor is it very well inspected against potentially insecure input.

However, this might be an opportunity for a Tool Labs tool. A tool could periodically (or, if limited for overload, directly after a change) scan wikis for gadget definitions, then fetch the text for the relevant js pages of the gadget, concatenate them, run them through jsduck and publish the result somewhere (e.g.

And though that on itself would be a great step (a gadget or template could show a link to there), it might even be possible to have the documentation be accessible from within the wiki (e.g. not just a link in a template pointing here, but actually without leaving the wiki).

First thing that comes to mind is the JSON manifests that jsduck generates in addition to the html, those can be interpreted cross-domain and rendered locally. Alternatively through a dialog and iframe the html can also be shown directly, of course.

If anything, it would be a good way to get started and 1) have gadget developers start documenting things in a consistent format and 2) see what problems come up.

I'm not saying we'll never integrate documentation natively for Gadgets.

But I think it's unlikely for technical reasons (not manpower or priority). One could also argue that this way Gadgets stays more focussed on its core purpose and leave this for another extension. So if there is an acceptable proposal for how to implement this natively, it should probably be in a separate extension.

Krinkle renamed this task from Auto-generated gadget documentation with JsDuck to Auto-generated gadget code documentation.Feb 25 2017, 3:01 AM
Krinkle updated the task description. (Show Details)