|
1 ====================================================================== |
|
2 |
|
3 DESCRIPTION: |
|
4 |
|
5 This is the source code for JsDoc Toolkit, an automatic documentation |
|
6 generation tool for JavaScript. It is written in JavaScript and is run |
|
7 from a command line (or terminal) using the Java and Mozilla's Rhino |
|
8 JavaScript runtime engine. |
|
9 |
|
10 Using this tool you can automatically turn JavaDoc-like comments in |
|
11 your JavaScript source code into published output files, such as HTML |
|
12 or XML. |
|
13 |
|
14 For more information, to report a bug, or to browse the technical |
|
15 documentation for this tool please visit the official JsDoc Toolkit |
|
16 project homepage at http://code.google.com/p/jsdoc-toolkit/ |
|
17 |
|
18 For the most up-to-date documentation on JsDoc Toolkit see the |
|
19 official wiki at http://code.google.com/p/jsdoc-toolkit/w/list |
|
20 |
|
21 ====================================================================== |
|
22 |
|
23 REQUIREMENTS: |
|
24 |
|
25 JsDoc Toolkit is known to work with: |
|
26 java version "1.6.0_03" |
|
27 Java(TM) SE Runtime Environment (build 1.6.0_03-b05) |
|
28 on Windows XP, |
|
29 and java version "1.5.0_13" |
|
30 Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05-241) |
|
31 on Mac OS X 10.4. |
|
32 |
|
33 Other versions of java may or may not work with JsDoc Toolkit. |
|
34 |
|
35 ====================================================================== |
|
36 |
|
37 USAGE: |
|
38 |
|
39 Running JsDoc Toolkit requires you to have Java installed on your |
|
40 computer. For more information see http://www.java.com/getjava/ |
|
41 |
|
42 Before running the JsDoc Toolkit app you should change your current |
|
43 working directory to the jsdoc-toolkit folder. Then follow the |
|
44 examples below, or as shown on the project wiki. |
|
45 |
|
46 On a computer running Windows a valid command line to run JsDoc |
|
47 Toolkit might look like this: |
|
48 |
|
49 > java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js |
|
50 |
|
51 On Mac OS X or Linux the same command would look like this: |
|
52 |
|
53 $ java -jar jsrun.jar app/run.js -a -t=templates/jsdoc mycode.js |
|
54 |
|
55 The above assumes your current working directory contains jsrun.jar, |
|
56 the "app" and "templates" subdirectories from the standard JsDoc |
|
57 Toolkit distribution and that the relative path to the code you wish |
|
58 to document is "mycode.js". |
|
59 |
|
60 The output documentation files will be saved to a new directory named |
|
61 "out" (by default) in the current directory, or if you specify a |
|
62 -d=somewhere_else option, to the somewhere_else directory. |
|
63 |
|
64 For help (usage notes) enter this on the command line: |
|
65 |
|
66 $ java -jar jsrun.jar app/run.js --help |
|
67 |
|
68 More information about the various command line options used by JsDoc |
|
69 Toolkit are available on the project wiki. |
|
70 |
|
71 ====================================================================== |
|
72 |
|
73 RUNNING VIA SHELL SCRIPT |
|
74 |
|
75 Avi Deitcher has contributed the file jsrun.sh with the following usage notes: |
|
76 |
|
77 A script to simplify running jsdoc from the command-line, especially when |
|
78 running from within a development or build environment such as ant. |
|
79 |
|
80 Normally, to run jsdoc, you need a command-line as the following: |
|
81 java -Djsdoc.dir=/some/long/dir/path/to/jsdoc -jar |
|
82 /some/long/dir/path/to/jsdoc/jsrun.jar /some/long/dir/path/to/jsdoc/app/run.js |
|
83 -t=template -r=4 /some/long/dir/path/to/my/src/code |
|
84 |
|
85 This can get tedious to redo time and again, and difficult to use from within a |
|
86 build environment. |
|
87 |
|
88 To simplify the process, jsrun.sh will automatically run this path, as well as |
|
89 passing through any arguments. |
|
90 |
|
91 Usage: jsrun.sh <run.js arguments> |
|
92 |
|
93 All <run.js arguments> will be passed through. |
|
94 Additionally, jsrun.sh will take the following actions: |
|
95 1) If the environment variable JSDOCDIR is set, it will add |
|
96 "-Djsdoc.dir=$JSDOCDIR" to the command-line |
|
97 2) If the environment variable JSDOCTEMPLATEDIR is set, it will add |
|
98 "-Djsdoc.template.dir=$JSDOCTEMPLATEDIR" to the command-line |
|
99 3) java with the appropriate path to jsrun.jar and run.js will be instantiated |
|
100 |
|
101 If not variables are set, it is assumed that the path to jsrun.jar and app/ is |
|
102 in the current working directory. |
|
103 |
|
104 Example: |
|
105 # jsrun.sh ./src/ |
|
106 Assuming JSDOCDIR=/some/path/to/my/jsdoc will cause the following command to |
|
107 execute: |
|
108 java -Djsdoc.dir=/some/path/to/my/jsdoc -jar /some/path/to/my/jsdoc/jsrun.jar |
|
109 /some/path/to/my/jsdoc/app/run.js ./src/ |
|
110 |
|
111 ====================================================================== |
|
112 |
|
113 TESTING: |
|
114 |
|
115 To run the suite of unit tests included with JsDoc Toolkit enter this |
|
116 on the command line: |
|
117 |
|
118 $ java -jar jsrun.jar app/run.js -T |
|
119 |
|
120 To see a dump of the internal data structure that JsDoc Toolkit has |
|
121 built from your source files use this command: |
|
122 |
|
123 $ java -jar jsrun.jar app/run.js mycode.js -Z |
|
124 |
|
125 ====================================================================== |
|
126 |
|
127 LICENSE: |
|
128 |
|
129 JSDoc.pm |
|
130 |
|
131 This project is based on the JSDoc.pm tool, created by Michael |
|
132 Mathews and Gabriel Reid. More information on JsDoc.pm can |
|
133 be found on the JSDoc.pm homepage: http://jsdoc.sourceforge.net/ |
|
134 |
|
135 Complete documentation on JsDoc Toolkit can be found on the project |
|
136 wiki at http://code.google.com/p/jsdoc-toolkit/w/list |
|
137 |
|
138 Rhino |
|
139 |
|
140 Rhino (JavaScript in Java) is open source and licensed by Mozilla |
|
141 under the MPL 1.1 or later/GPL 2.0 or later licenses, the text of |
|
142 which is available at http://www.mozilla.org/MPL/ |
|
143 |
|
144 You can obtain the source code for Rhino from the Mozilla web site at |
|
145 http://www.mozilla.org/rhino/download.html |
|
146 |
|
147 JsDoc Toolkit is a larger work that uses the Rhino JavaScript engine |
|
148 but is not derived from it in any way. The Rhino library is used |
|
149 without modification and without any claims whatsoever. |
|
150 |
|
151 The Rhino Debugger |
|
152 |
|
153 You can obtain more information about the Rhino Debugger from the |
|
154 Mozilla web site at http://www.mozilla.org/rhino/debugger.html |
|
155 |
|
156 JsDoc Toolkit is a larger work that uses the Rhino Debugger but |
|
157 is not derived from it in any way. The Rhino Debugger is used |
|
158 without modification and without any claims whatsoever. |
|
159 |
|
160 JsDoc Toolkit |
|
161 |
|
162 All code specific to JsDoc Toolkit are free, open source and licensed |
|
163 for use under the X11/MIT License. |
|
164 |
|
165 JsDoc Toolkit is Copyright (c)2009 Michael Mathews <micmath@gmail.com> |
|
166 |
|
167 This program is free software; you can redistribute it and/or |
|
168 modify it under the terms below. |
|
169 |
|
170 Permission is hereby granted, free of charge, to any person obtaining |
|
171 a copy of this software and associated documentation files (the |
|
172 "Software"), to deal in the Software without restriction, including |
|
173 without limitation the rights to use, copy, modify, merge, publish, |
|
174 distribute, sublicense, and/or sell copies of the Software, and to |
|
175 permit persons to whom the Software is furnished to do so, subject to |
|
176 the following conditions: The above copyright notice and this |
|
177 permission notice must be included in all copies or substantial |
|
178 portions of the Software. |
|
179 |
|
180 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, |
|
181 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF |
|
182 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. |
|
183 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY |
|
184 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, |
|
185 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE |
|
186 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |