Last modified: 2014-08-13 12:29:51 UTC
I believe gadget developers would benefit from having autogenerated documentation, using jsDuck, as we currently have for MediaWiki code. See also: * http://lists.wikimedia.org/pipermail/wikitech-l/2013-January/065751.html * http://lists.wikimedia.org/pipermail/wikitech-l/2013-July/070439.html
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.
