Generate documentation from the JavaScript code automatically using JSDuck.
The way to do this is documented here: https://www.mediawiki.org/wiki/Continuous_integration/Documentation_generation
Description
Details
- Reference
- bz40657
Status | Subtype | Assigned | Task | ||
---|---|---|---|---|---|
Invalid | None | T108946 [Epic] Improve the development infrastructure | |||
Resolved | • Ladsgroup | T42657 [Task] Wikibase: Auto-generate documentation for JavaScript code |
Event Timeline
Decided on this method: http://xiewenjie.com/doxygen-js/use-doxygen-to-document-javascript
I see no reason to mark this RESOLVED LATER. If it's not going to be done now, lower the priority.
This is the Wikidata bug, the WMF one is over here: https://bugzilla.wikimedia.org/show_bug.cgi?id=40143
For Wikidata we set up a script that converts .js to .cpp files [1]. We had to adjust parameter names to match the WM coding conventions [2].
But the JS parser fails to parse our prototype definitions, so classes and their hierarchy are not recognized.
We will come back to this later.
[1] http://xiewenjie.com/doxygen-js/use-doxygen-to-document-javascript
[2] http://www.mediawiki.org/wiki/Manual:Coding_conventions/JavaScript#Documentation_comments
[Removing RESOLVED LATER as discussed in http://lists.wikimedia.org/pipermail/wikitech-l/2012-November/064240.html . Reopening and setting priority to "Lowest" as discussed on IRC.
For future reference, please use either RESOLVED WONTFIX (for issues that will not be fixed), or simply set lowest priority. Thanks a lot!]
Would be nice to get that ticket back on track as, by now, there is complete code documentation in place for the JS components / JS part of the components DataModel, API, Serialization, DataTypes, DataValues and ValueView as well as a few single modules in Wikibase (like the entity selector widget).
In general, the documentation has been made compatible with the standards in core. Consequently, JSDuck should most likely be used for generating the documentation output as well. For the referenced components, it is possible to generate a proper documentation locally already.
Yes, jsduck is working well for several WMF projects and can do amazing things like live editable JS preview, see e.g. https://doc.wikimedia.org/oojs-ui/master/#!/api/OO.ui.Toolbar
WMF would be happy to host automatically-generated documentation for Wikibase on https://doc.wikimedia.org along with everything else. It's clearly doable, but only a few people know the Jenkins job builder setup for it.
The javascript documentation is generated with jsduck and published at https://doc.wikimedia.org/Wikibase/master/js/
That has been enabled by @Ladsgroup with bf53cd87c23b0146150fefe89bbfd22afd891379 in October 2016.