← Back to branch summary

~jstys-z/helioviewer.org/client5

« back to all changes in this revision

Viewing changes to scripts/jsdoc-toolkit/README.txt

  • Committer: Michael Lynch
  • Date: 2008-02-01 06:21:07 UTC
  • Revision ID: mike@mike-desktop-20080201062107-uhqip0rcpsfc91mq
Initial import

Show diffs side-by-side

added added

removed removed

Lines of Context:
scripts/jsdoc-toolkit/README.txt
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 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_19"
30
 
Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_19-b02-304)
31
 
on Mac OS X 10.5.
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 build environment.
86
 
 
87
 
To simplify the process, jsrun.sh will automatically run this path, as well as passing through any arguments.
88
 
 
89
 
Usage: jsrun.sh <run.js arguments>
90
 
 
91
 
All <run.js arguments> will be passed through.
92
 
Additionally, jsrun.sh will take the following actions:
93
 
1) If the environment variable JSDOCDIR is set, it will add
94
 
"-Djsdoc.dir=$JSDOCDIR" to the command-line
95
 
2) If the environment variable JSDOCTEMPLATEDIR is set, it will add
96
 
"-Djsdoc.template.dir=$JSDOCTEMPLATEDIR" to the command-line
97
 
3) java with the appropriate path to jsrun.jar and run.js will be instantiated
98
 
 
99
 
If not variables are set, it is assumed that the path to jsrun.jar and app/ is in the current working directory.
100
 
 
101
 
Example:
102
 
# jsrun.sh ./src/
103
 
Assuming JSDOCDIR=/some/path/to/my/jsdoc will cause the following command to
104
 
execute:
105
 
java -Djsdoc.dir=/some/path/to/my/jsdoc -jar /some/path/to/my/jsdoc/jsrun.jar
106
 
/some/path/to/my/jsdoc/app/run.js ./src/
107
 
 
108
 
======================================================================
109
 
 
110
 
TESTING:
111
 
 
112
 
To run the suite of unit tests included with JsDoc Toolkit enter this
113
 
on the command line:
114
 
 
115
 
$ java -jar jsrun.jar app/run.js -T
116
 
 
117
 
To see a dump of the internal data structure that JsDoc Toolkit has
118
 
built from your source files use this command:
119
 
 
120
 
$ java -jar jsrun.jar app/run.js mycode.js -Z
121
 
 
122
 
======================================================================
123
 
 
124
 
LICENSE:
125
 
 
126
 
JSDoc.pm
127
 
 
128
 
This project is based on the JSDoc.pm tool, created by Michael
129
 
Mathews and Gabriel Reid. More information on JsDoc.pm can
130
 
be found on the JSDoc.pm homepage: http://jsdoc.sourceforge.net/
131
 
 
132
 
Complete documentation on JsDoc Toolkit can be found on the project
133
 
wiki at http://code.google.com/p/jsdoc-toolkit/w/list
134
 
 
135
 
Rhino
136
 
 
137
 
Rhino (JavaScript in Java) is open source and licensed by Mozilla
138
 
under the MPL 1.1 or later/GPL 2.0 or later licenses, the text of
139
 
which is available at http://www.mozilla.org/MPL/
140
 
 
141
 
You can obtain the source code for Rhino from the Mozilla web site at
142
 
http://www.mozilla.org/rhino/download.html
143
 
 
144
 
JsDoc Toolkit is a larger work that uses the Rhino JavaScript engine
145
 
but is not derived from it in any way. The Rhino library is used 
146
 
without modification and without any claims whatsoever.
147
 
 
148
 
The Rhino Debugger
149
 
 
150
 
You can obtain more information about the Rhino Debugger from the 
151
 
Mozilla web site at http://www.mozilla.org/rhino/debugger.html
152
 
 
153
 
JsDoc Toolkit is a larger work that uses the Rhino Debugger but
154
 
is not derived from it in any way. The Rhino Debugger is used
155
 
without modification and without any claims whatsoever.
156
 
 
157
 
JsDoc Toolkit
158
 
 
159
 
All code specific to JsDoc Toolkit are free, open source and licensed
160
 
for use under the X11/MIT License.
161
 
 
162
 
JsDoc Toolkit is Copyright (c)2009 Michael Mathews <micmath@gmail.com>
163
 
 
164
 
This program is free software; you can redistribute it and/or
165
 
modify it under the terms below.
166
 
 
167
 
Permission is hereby granted, free of charge, to any person obtaining
168
 
a copy of this software and associated documentation files (the
169
 
"Software"), to deal in the Software without restriction, including
170
 
without limitation the rights to use, copy, modify, merge, publish,
171
 
distribute, sublicense, and/or sell copies of the Software, and to
172
 
permit persons to whom the Software is furnished to do so, subject to
173
 
the following conditions: The above copyright notice and this
174
 
permission notice must be included in all copies or substantial
175
 
portions of the Software.
176
 
 
177
 
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
178
 
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
179
 
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
180
 
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
181
 
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
182
 
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
183
 
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.