1 | JSDoc 3
|
2 | =======
|
3 | [![Build Status](https://img.shields.io/travis/jsdoc3/jsdoc.svg)](http://travis-ci.org/jsdoc3/jsdoc)
|
4 |
|
5 | An API documentation generator for JavaScript.
|
6 |
|
7 | Want to contribute to JSDoc? Please read `CONTRIBUTING.md`.
|
8 |
|
9 | Installation and Usage
|
10 | ----------------------
|
11 |
|
12 | You can run JSDoc on either Node.js or Mozilla Rhino.
|
13 |
|
14 | ### Node.js
|
15 |
|
16 | Native support for Node.js is available in JSDoc 3.3.0 and later. JSDoc
|
17 | supports Node.js 0.10 and later.
|
18 |
|
19 | #### Installing JSDoc for Node.js
|
20 |
|
21 | You can install JSDoc in your project's `node_modules` folder, or you can
|
22 | install it globally.
|
23 |
|
24 | To install the latest alpha version:
|
25 |
|
26 | npm install jsdoc@"<=3.3.0"
|
27 |
|
28 | To install the latest development version:
|
29 |
|
30 | npm install git+https://github.com/jsdoc3/jsdoc.git
|
31 |
|
32 | #### Running JSDoc with Node.js
|
33 |
|
34 | If you installed JSDoc locally, the JSDoc command-line tool is available in
|
35 | `./node_modules/.bin`. To generate documentation for the file
|
36 | `yourJavaScriptFile.js`:
|
37 |
|
38 | ./node_modules/.bin/jsdoc yourJavaScriptFile.js
|
39 |
|
40 | Or if you installed JSDoc globally, simply run the `jsdoc` command:
|
41 |
|
42 | jsdoc yourJavaScriptFile.js
|
43 |
|
44 | By default, the generated documentation is saved in a directory named `out`. You
|
45 | can use the `--destination` (`-d`) option to specify another directory.
|
46 |
|
47 | Run `jsdoc --help` for a complete list of command-line options.
|
48 |
|
49 | ### Mozilla Rhino
|
50 |
|
51 | All versions of JSDoc 3 run on a customized version of Mozilla Rhino, which
|
52 | requires Java. You can run JSDoc 3 on Java 1.6 and later.
|
53 |
|
54 | #### Installing JSDoc for Mozilla Rhino
|
55 |
|
56 | To install JSDoc, download a .zip file for the
|
57 | [latest development version](https://github.com/jsdoc3/jsdoc/archive/master.zip)
|
58 | or a [previous release](https://github.com/jsdoc3/jsdoc/tags).
|
59 |
|
60 | You can also use git to clone the
|
61 | [JSDoc repository](https://github.com/jsdoc3/jsdoc):
|
62 |
|
63 | git clone git+https://github.com/jsdoc3/jsdoc.git
|
64 |
|
65 | The JSDoc repository includes a
|
66 | [customized version of Mozilla Rhino](https://github.com/jsdoc3/rhino). Make
|
67 | sure your Java classpath does not include any other versions of Rhino. (On OS X,
|
68 | you may need to remove the file `~/Library/Java/Extensions/js.jar`.)
|
69 |
|
70 | **Note**: In JSDoc 3.3.0 and later, if you need to run JSDoc on Mozilla Rhino,
|
71 | do not install JSDoc with npm. Use one of the methods described above.
|
72 |
|
73 | #### Running JSDoc with Mozilla Rhino
|
74 |
|
75 | On OS X, Linux, and other POSIX systems, to generate documentation for the file
|
76 | `yourJavaScriptFile.js`:
|
77 |
|
78 | ./jsdoc yourJavaScriptFile.js
|
79 |
|
80 | Or on Windows:
|
81 |
|
82 | jsdoc yourJavaScriptFile.js
|
83 |
|
84 | By default, the generated documentation is saved in a directory named `out`. You
|
85 | can use the `--destination` (`-d`) option to specify another directory.
|
86 |
|
87 | Run `jsdoc --help` for a complete list of command-line options.
|
88 |
|
89 |
|
90 | Templates and Build Tools
|
91 | -------------------------
|
92 |
|
93 | The JSDoc community has created numerous templates and other tools to help you
|
94 | generate and customize your documentation. Here are just a few:
|
95 |
|
96 | ### Templates
|
97 |
|
98 | + [jaguarjs-jsdoc](https://github.com/davidshimjs/jaguarjs-jsdoc)
|
99 | ([example](http://davidshimjs.github.io/jaguarjs/doc))
|
100 | + [DocStrap](https://github.com/terryweiss/docstrap)
|
101 | + [jsdoc3Template](https://github.com/DBCDK/jsdoc3Template)
|
102 | ([example](https://github.com/danyg/jsdoc3Template/wiki#wiki-screenshots))
|
103 | + [minami](https://github.com/Nijikokun/minami)
|
104 |
|
105 | ### Build Tools
|
106 |
|
107 | + [JSDoc Grunt plugin](https://github.com/krampstudio/grunt-jsdoc)
|
108 | + [JSDoc ant task](https://github.com/jannon/jsdoc3-ant-task)
|
109 |
|
110 |
|
111 | For More Information
|
112 | --------------------
|
113 |
|
114 | + Documentation is available at [Use JSDoc](http://usejsdoc.org).
|
115 | + Contribute to the docs at [jsdoc3/jsdoc3.github.com](https://github.com/jsdoc3/jsdoc3.github.com).
|
116 | + Ask for help on the [JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).
|
117 | + Post questions tagged `jsdoc` to [Stack
|
118 | Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
|
119 |
|
120 | License
|
121 | -------
|
122 |
|
123 | JSDoc 3 is copyright (c) 2011-2014 Michael Mathews <micmath@gmail.com> and the
|
124 | [contributors to JSDoc](https://github.com/jsdoc3/jsdoc/graphs/contributors).
|
125 |
|
126 | JSDoc 3 is free software, licensed under the Apache License, Version 2.0. See
|
127 | the file `LICENSE.md` in this distribution for more details.
|