Page MenuHomePhabricator

Auto-generated gadget code documentation
Open, LowPublic

Description

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:

Details

Reference
bz51651

Related Objects

StatusAssignedTask
Declined Reguyla
ResolvedNemo_bis
OpenNone
OpenNone
OpenNone
OpenNone
DuplicateNone
StalledNone
OpenNone
OpenNone
ResolvedTTO
ResolvedNone
OpenNone
ResolvedNone
ResolvedNone
StalledNone
ResolvedLegoktm
OpenNone
DuplicateNone
ResolvedSamwilson
ResolvedNone
OpenNone
OpenNone
OpenRical
DeclinedNone
OpenNone
OpenNone
OpenNone
StalledNone
ResolvedNone
OpenNone
OpenNone
InvalidJackmcbarn
OpenNone
DeclinedRical
OpenRical
OpenNone
OpenNone
OpenNone
OpenNone
OpenNone
OpenNone
OpenTK-999

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).
He7d3r created this task.Jul 19 2013, 1:42 AM

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. tools.wmflabs.org/gadgetdoc/commonswiki/Stockphoto).

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.

Restricted Application added a subscriber: Aklapper. · View Herald TranscriptJan 6 2016, 9:27 PM
Catrope removed a subscriber: Catrope.Jan 15 2016, 11:00 PM
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)
Krinkle removed a subscriber: Krinkle.