node-query/node_modules/jsdoc/README.md

127 lines
4.0 KiB
Markdown
Raw Normal View History

2014-10-20 16:56:45 -04:00
JSDoc 3
=======
2014-10-22 10:11:40 -04:00
[![Build Status](https://img.shields.io/travis/jsdoc3/jsdoc.svg)](http://travis-ci.org/jsdoc3/jsdoc)
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
An API documentation generator for JavaScript.
2014-10-20 16:56:45 -04:00
Want to contribute to JSDoc? Please read `CONTRIBUTING.md`.
2014-10-22 10:11:40 -04:00
Installation and Usage
----------------------
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
You can run JSDoc on either Node.js or Mozilla Rhino.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
### Node.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Native support for Node.js is available in JSDoc 3.3.0 and later. JSDoc
supports Node.js 0.10 and later.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
#### 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"
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
To install the latest development version:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
npm install git+https://github.com/jsdoc3/jsdoc.git
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
#### Running JSDoc with Node.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
If you installed JSDoc locally, the JSDoc command-line tool is available in
`./node_modules/.bin`. To generate documentation for the file
`yourJavaScriptFile.js`:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
./node_modules/.bin/jsdoc yourJavaScriptFile.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Or if you installed JSDoc globally, simply run the `jsdoc` command:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
jsdoc yourJavaScriptFile.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
By default, the generated documentation is saved in a directory named `out`. You
can use the `--destination` (`-d`) option to specify another directory.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Run `jsdoc --help` for a complete list of command-line options.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
### 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](https://github.com/jsdoc3/jsdoc/archive/master.zip)
or a [previous release](https://github.com/jsdoc3/jsdoc/tags).
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
You can also use git to clone the
[JSDoc repository](https://github.com/jsdoc3/jsdoc):
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
git clone git+https://github.com/jsdoc3/jsdoc.git
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
The JSDoc repository includes a
[customized version of Mozilla Rhino](https://github.com/jsdoc3/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`.)
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
**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.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
#### Running JSDoc with Mozilla Rhino
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
On OS X, Linux, and other POSIX systems, to generate documentation for the file
`yourJavaScriptFile.js`:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
./jsdoc yourJavaScriptFile.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Or on Windows:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
jsdoc yourJavaScriptFile.js
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
By default, the generated documentation is saved in a directory named `out`. You
can use the `--destination` (`-d`) option to specify another directory.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Run `jsdoc --help` for a complete list of command-line options.
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
Templates and Build Tools
-------------------------
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
The JSDoc community has created numerous templates and other tools to help you
generate and customize your documentation. Here are just a few:
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
### Templates
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
+ [jaguarjs-jsdoc](https://github.com/davidshimjs/jaguarjs-jsdoc)
([example](http://davidshimjs.github.io/jaguarjs/doc))
+ [DocStrap](https://github.com/terryweiss/docstrap)
+ [jsdoc3Template](https://github.com/DBCDK/jsdoc3Template)
([example](https://github.com/danyg/jsdoc3Template/wiki#wiki-screenshots))
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
### Build Tools
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
+ [JSDoc Grunt plugin](https://github.com/krampstudio/grunt-jsdoc)
+ [JSDoc ant task](https://github.com/jannon/jsdoc3-ant-task)
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
For More Information
--------------------
2014-10-20 16:56:45 -04:00
2014-10-22 10:11:40 -04:00
+ Documentation is available at [Use JSDoc](http://usejsdoc.org).
+ Contribute to the docs at [jsdoc3/jsdoc3.github.com](https://github.com/jsdoc3/jsdoc3.github.com).
2015-01-28 15:33:44 -05:00
+ Ask for help on the [JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).
2014-10-22 10:11:40 -04:00
+ Post questions tagged `jsdoc` to [Stack
Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
2014-10-20 16:56:45 -04:00
License
-------
2014-10-22 10:11:40 -04:00
JSDoc 3 is copyright (c) 2011-2014 Michael Mathews <micmath@gmail.com> and the
[contributors to JSDoc](https://github.com/jsdoc3/jsdoc/graphs/contributors).
2014-10-20 16:56:45 -04:00
JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See
the file `LICENSE.md` in this distribution for more details.