Page MenuHomePhabricator

[Task] Wikibase: Auto-generate documentation for JavaScript code
Closed, ResolvedPublic

Description

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

Details

Reference
bz40657

Event Timeline

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

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!]

Lydia_Pintscher removed a subscriber: Unknown Object (MLST).
Lydia_Pintscher removed a subscriber: Unknown Object (MLST).

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.

JanZerebecki renamed this task from Auto-generated documentation for JavaScript code based on already existing doxygen comments to [Task] Wikibase: Auto-generated documentation for JavaScript code.Sep 10 2015, 12:51 PM
JanZerebecki updated the task description. (Show Details)
JanZerebecki set Security to None.
JanZerebecki renamed this task from [Task] Wikibase: Auto-generated documentation for JavaScript code to [Task] Wikibase: Auto-generate documentation for JavaScript code.Sep 10 2015, 12:53 PM
JanZerebecki raised the priority of this task from Low to Medium.
JanZerebecki updated the task description. (Show Details)
JanZerebecki moved this task from incoming to ready to go on the Wikidata board.
hashar assigned this task to Ladsgroup.
hashar added subscribers: Ladsgroup, hashar.

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.