Joey Parrish
8ba088a38f
We were not able to get our externs generated by the Closure compiler. There were many issues with the Closure-generated externs, including the order of the externs and the replacement of record types and enums with their underlying types. We made a few attempts to patch the compiler, but could not get our patches accepted upstream. This change introduces a new script to generate our externs from scratch. It uses a JavaScript parser called 'esprima'. Some interfaces need to be exported to the generated externs, but are not actually attached to the namespace by the compiler. For this, we introduce a new annotation. These are the currently-supported export annotations: - @export: truly exported (attached to namespace) by the compiler - @expose: truly exposed (not renamed) by the compiler - @exportDoc: considered part of the exports in the docs - @exportInterface: considered part of the exports in generated externs These annotations are now documented in docs/design/export.md Change-Id: I33bf7384889c14c9edb0fa5f11caa7c4f4d79af6
JSDoc 3
An API documentation generator for JavaScript.
Want to contribute to JSDoc? Please read CONTRIBUTING.md.
Installation and Usage
You can run JSDoc on either Node.js or Mozilla Rhino.
Node.js
Native support for Node.js is available in JSDoc 3.3.0 and later. JSDoc supports Node.js 0.10 and later.
Installing JSDoc for Node.js
You can install JSDoc in your project's node_modules folder, or you can
install it globally.
To install the latest alpha version:
npm install jsdoc@"<=3.3.0"
To install the latest development version:
npm install git+https://github.com/jsdoc3/jsdoc.git
Running JSDoc with Node.js
If you installed JSDoc locally, the JSDoc command-line tool is available in
./node_modules/.bin. To generate documentation for the file
yourJavaScriptFile.js:
./node_modules/.bin/jsdoc yourJavaScriptFile.js
Or if you installed JSDoc globally, simply run the jsdoc command:
jsdoc yourJavaScriptFile.js
By default, the generated documentation is saved in a directory named out. You
can use the --destination (-d) option to specify another directory.
Run jsdoc --help for a complete list of command-line options.
Mozilla Rhino
All versions of JSDoc 3 run on a customized version of Mozilla Rhino, which requires Java. You can run JSDoc 3 on Java 1.6 and later.
Installing JSDoc for Mozilla Rhino
To install JSDoc, download a .zip file for the latest development version or a previous release.
You can also use git to clone the JSDoc repository:
git clone git+https://github.com/jsdoc3/jsdoc.git
The JSDoc repository includes a
customized version of Mozilla Rhino. Make
sure your Java classpath does not include any other versions of Rhino. (On OS X,
you may need to remove the file ~/Library/Java/Extensions/js.jar.)
Note: In JSDoc 3.3.0 and later, if you need to run JSDoc on Mozilla Rhino, do not install JSDoc with npm. Use one of the methods described above.
Running JSDoc with Mozilla Rhino
On OS X, Linux, and other POSIX systems, to generate documentation for the file
yourJavaScriptFile.js:
./jsdoc yourJavaScriptFile.js
Or on Windows:
jsdoc yourJavaScriptFile.js
By default, the generated documentation is saved in a directory named out. You
can use the --destination (-d) option to specify another directory.
Run jsdoc --help for a complete list of command-line options.
Templates and Build Tools
The JSDoc community has created numerous templates and other tools to help you generate and customize your documentation. Here are just a few:
Templates
Build Tools
Generating Typeface Fonts
JSDoc 3 uses the OpenSans typeface, the fonts for which can be re-generated as follows:
- Open the OpenSans page at Font Squirrel.
- Click on the 'Webfont Kit' tab.
- Either leave the subset drop-down as 'Western Latin (Default)', or if we decide we need more glyphs than change it to 'No Subsetting'.
- Click the 'DOWNLOAD @FONT-FACE KIT' button.
- For each typeface variant we plan to use, copy the 'eot', 'svg' and 'woff' files into the 'templates/default/static/fonts' directory.
For More Information
- Documentation is available at Use JSDoc.
- Contribute to the docs at jsdoc3/jsdoc3.github.com.
- Ask for help on the JSDoc Users mailing list.
- Post questions tagged
jsdocto Stack Overflow.
License
JSDoc 3 is copyright (c) 2011-2014 Michael Mathews micmath@gmail.com and the contributors to JSDoc.
JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See
the file LICENSE.md in this distribution for more details.