Page MenuHomePhabricator

Implement auto-generated documentation for JavaScript resources
Closed, ResolvedPublic

Description

The JavaScript code in core/resources has lots of Doxygen-style comments, but http://svn.mediawiki.org/doc/ displays nothing for it, I assume because it's not PHP.

I hoped this would be as simple as adding .js to FILE_PATTERNS in maintenance/Doxyfile... however I tried this locally and the only documentation it seems to generate for all the resources/*.js files that I checked is

Variables
function 	mw

It may be that mwdoc-filter.php needs to be adjusted for .js files, but it could be that .js files need to be pre-processed, see "For those working with JavaScript..." in http://www.stack.nl/~dimitri/doxygen/helpers.html


Version: 1.20.x
Severity: normal

Details

Reference
bz40143

Event Timeline

bzimport raised the priority of this task from to Medium.Nov 22 2014, 12:46 AM
bzimport set Reference to bz40143.

I agree we should definitely do this. We don't necessarily have to use Doxygen. There are tools specifically for JavaScript.

JSDoc has been suggested before (http://www.mail-archive.com/wikitech-l@lists.wikimedia.org/msg09167.html). If that doesn't work well, I've used YUIDoc in the past.

But the bottom line is we have to pick one, get it running, then go through and fix the comments (whatever we pick we'll at least have to make adjustments).

See also https://www.mediawiki.org/wiki/Requests_for_comment/Documentation_overhaul#Implementation_ideas (which is broader in scope).

Krinkle has been working on it by using JSDuck. The preliminary version is available from https://doc.wikimedia.org/ then MediaWiki (JS). That points to https://doc.wikimedia.org/mediawiki-core/master/js/