Parse/save/display JavaScript files

Migrated issue

Reported by: Jaza

Problem/Motivation

The API module currently does not display JavaScript files or documentation. There is important Drupal functionality that is coded in JavaScript, so it probably should.

Proposed resolution

Adopt a parser for JavaScript documentation, and use its output in the API module.

Options:

a) JSDoc v. 3:
- Project: https://github.com/jsdoc3/jsdoc
- Reference: http://usejsdoc.org/
- This one has been extensively evaluated as of May 2012, and is both unstable, and unusable in its present form. There is a summary of findings, with sample output, in comment #63.

b) YUIDoc
- Project: http://yui.github.com/yuidoc/
- Reference: http://yui.github.com/yuidoc/syntax/index.html
- Preliminary evaluation (comment #65) is not favorable.

We also need to adopt some JavaScript documentation standards, which is a separate issue:
#1337022: [policy, no patch] Create/adopt JavaScript docs standards compatible with a JS documentation parser

Remaining tasks

  1. Choose a documentation parser.
  2. Develop standards for documentation that will work with the documentation parser for JS (separate issue #1337022: [policy, no patch] Create/adopt JavaScript docs standards compatible with a JS documentation parser).
  3. Integrate the parser output into the API module. The suggested process would be to run this generator separately to produce machine-readable output, and then read this output with the API module, save it in the database, and display it like PHP docs we display now.

User interface changes

JavaScript files and documentation would be parsed and displayed with the API module (and on api.drupal.org).

API changes

None.

Original report by Jaza

I was browsing around drupaldocs.org, and I noticed that the newly added JavaScript code is not documented on this site. Drupal CVS (HEAD) now has three JavaScript files - autocomplete.js, collapse.js, and drupal.js - and all up this means that there are 28 JS functions in Drupal core. The AJAX functions make up most of this code, but more recently the collapsible elements functions were added, and no doubt the number of JS functions is only going to get bigger from here on.

I understand that although Doxygen doesn't support JavaScript natively, there is a utility available (a perl script) that allows JavaScript to be parsed by Doxygen:

http://www.stack.nl/~dimitri/doxygen/helpers.html

How hard would it be to get the API module to support JavaScript? We really need to get those JavaScript functions documented in the drupaldocs.org API reference. 28 functions is a lot of undocumented code in Drupal core. I guess this isn't a huge worry for now, seeing that the JS is only in HEAD. But when Drupal 4.7 is eventually released - and although it seems like it's ages away, it's really not that far off - this really should be done.