8f1d892fbf
Squashed commit of the following:
commit 11da3dbe026fb0c76d619f0295a195d1f012462e
Author: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Fri Nov 7 14:42:02 2014 -0800
add test for #758
commit f3e001d549c5e0e69e50b231f375da92f3e8f688
Merge: df1f4bd d551131
Author: Jeff Williams <jeffrey.l.williams@gmail.com>
Date: Fri Nov 7 14:32:30 2014 -0800
Merge remote-tracking branch 'danorton/patch-1' into 758
commit d5511316468eb93f852c51fab5eec380bcfee4b4
Author: Daniel Norton <daniel@danielnorton.com>
Date: Wed Sep 3 17:00:49 2014 -0500
Prevent filenames beginning with underscore
A lot of related software (most notably github.io and the default configuration of jsdoc itself) ignores files with names that begin with an underscore, but the makeUniqueFilename() creates such filenames when the incoming filename is blank. This patch modifies makeUniqueFilename() to insert the ASCII letter "X" before empty filenames or filenames that begin with an underscore.
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.