+
−======================================================================
+
−
+
−DESCRIPTION:
+
−
+
−This is the source code for JsDoc Toolkit, an automatic documentation
+
−generation tool for JavaScript. It is written in JavaScript and is run
+
−from a command line (or terminal) using the Java and Mozilla's Rhino
+
−JavaScript runtime engine.
+
−
+
−Using this tool you can automatically turn JavaDoc-like comments in
+
−your JavaScript source code into published output files, such as HTML
+
−or XML.
+
−
+
−For more information, to report a bug, or to browse the technical
+
−documentation for this tool please visit the official JsDoc Toolkit
+
−project homepage at http://code.google.com/p/jsdoc-toolkit/
+
−
+
−For the most up-to-date documentation on JsDoc Toolkit see the 
+
−official wiki at http://code.google.com/p/jsdoc-toolkit/w/list
+
−
+
−======================================================================
+
−
+
−REQUIREMENTS:
+
−
+
−JsDoc Toolkit is known to work with:
+
−java version "1.6.0_03"
+
−Java(TM) SE Runtime Environment (build 1.6.0_03-b05)
+
−on Windows XP,
+
−and java version "1.5.0_13"
+
−Java(TM) 2 Runtime Environment, Standard Edition (build 1.5.0_13-b05-241)
+
−on Mac OS X 10.4.
+
−
+
−Other versions of java may or may not work with JsDoc Toolkit.
+
−
+
−======================================================================
+
−
+
−USAGE:
+
−
+
−Running JsDoc Toolkit requires you to have Java installed on your
+
−computer. For more information see http://www.java.com/getjava/
+
−
+
−Before running the JsDoc Toolkit app you should change your current
+
−working directory to the jsdoc-toolkit folder. Then follow the
+
−examples below, or as shown on the project wiki.
+
−
+
−On a computer running Windows a valid command line to run JsDoc
+
−Toolkit might look like this:
+
−
+
−> java -jar jsrun.jar app\run.js -a -t=templates\jsdoc mycode.js
+
−
+
−On Mac OS X or Linux the same command would look like this:
+
−
+
−$ java -jar jsrun.jar app/run.js -a -t=templates/jsdoc mycode.js
+
−
+
−The above assumes your current working directory contains jsrun.jar,
+
−the "app" and "templates" subdirectories from the standard JsDoc
+
−Toolkit distribution and that the relative path to the code you wish
+
−to document is "mycode.js".
+
−
+
−The output documentation files will be saved to a new directory named
+
−"out" (by default) in the current directory, or if you specify a
+
−-d=somewhere_else option, to the somewhere_else directory.
+
−
+
−For help (usage notes) enter this on the command line:
+
−
+
−$ java -jar jsrun.jar app/run.js --help
+
−
+
−More information about the various command line options used by JsDoc
+
−Toolkit are available on the project wiki.
+
−
+
−======================================================================
+
−
+
−RUNNING VIA SHELL SCRIPT
+
−
+
−Avi Deitcher has contributed the file jsrun.sh with the following usage notes:
+
−
+
−A script to simplify running jsdoc from the command-line, especially when
+
−running from within a development or build environment such as ant.
+
−
+
−Normally, to run jsdoc, you need a command-line as the following:
+
−java -Djsdoc.dir=/some/long/dir/path/to/jsdoc -jar
+
−/some/long/dir/path/to/jsdoc/jsrun.jar /some/long/dir/path/to/jsdoc/app/run.js
+
−-t=template -r=4 /some/long/dir/path/to/my/src/code
+
−
+
−This can get tedious to redo time and again, and difficult to use from within a
+
−build environment.
+
−
+
−To simplify the process, jsrun.sh will automatically run this path, as well as
+
−passing through any arguments.
+
−
+
−Usage: jsrun.sh <run.js arguments>
+
−
+
−All <run.js arguments> will be passed through.
+
−Additionally, jsrun.sh will take the following actions:
+
−1) If the environment variable JSDOCDIR is set, it will add
+
−"-Djsdoc.dir=$JSDOCDIR" to the command-line
+
−2) If the environment variable JSDOCTEMPLATEDIR is set, it will add
+
−"-Djsdoc.template.dir=$JSDOCTEMPLATEDIR" to the command-line
+
−3) java with the appropriate path to jsrun.jar and run.js will be instantiated
+
−
+
−If not variables are set, it is assumed that the path to jsrun.jar and app/ is
+
−in the current working directory.
+
−
+
−Example:
+
−# jsrun.sh ./src/
+
−Assuming JSDOCDIR=/some/path/to/my/jsdoc will cause the following command to
+
−execute:
+
−java -Djsdoc.dir=/some/path/to/my/jsdoc -jar /some/path/to/my/jsdoc/jsrun.jar
+
−/some/path/to/my/jsdoc/app/run.js ./src/
+
−
+
−======================================================================
+
−
+
−TESTING:
+
−
+
−To run the suite of unit tests included with JsDoc Toolkit enter this
+
−on the command line:
+
−
+
−$ java -jar jsrun.jar app/run.js -T
+
−
+
−To see a dump of the internal data structure that JsDoc Toolkit has
+
−built from your source files use this command:
+
−
+
−$ java -jar jsrun.jar app/run.js mycode.js -Z
+
−
+
−======================================================================
+
−
+
−LICENSE:
+
−
+
−JSDoc.pm
+
−
+
−This project is based on the JSDoc.pm tool, created by Michael
+
−Mathews and Gabriel Reid. More information on JsDoc.pm can
+
−be found on the JSDoc.pm homepage: http://jsdoc.sourceforge.net/
+
−
+
−Complete documentation on JsDoc Toolkit can be found on the project
+
−wiki at http://code.google.com/p/jsdoc-toolkit/w/list
+
−
+
−Rhino
+
−
+
−Rhino (JavaScript in Java) is open source and licensed by Mozilla
+
−under the MPL 1.1 or later/GPL 2.0 or later licenses, the text of
+
−which is available at http://www.mozilla.org/MPL/
+
−
+
−You can obtain the source code for Rhino from the Mozilla web site at
+
−http://www.mozilla.org/rhino/download.html
+
−
+
−JsDoc Toolkit is a larger work that uses the Rhino JavaScript engine
+
−but is not derived from it in any way. The Rhino library is used 
+
−without modification and without any claims whatsoever.
+
−
+
−The Rhino Debugger
+
−
+
−You can obtain more information about the Rhino Debugger from the 
+
−Mozilla web site at http://www.mozilla.org/rhino/debugger.html
+
−
+
−JsDoc Toolkit is a larger work that uses the Rhino Debugger but
+
−is not derived from it in any way. The Rhino Debugger is used
+
−without modification and without any claims whatsoever.
+
−
+
−JsDoc Toolkit
+
−
+
−All code specific to JsDoc Toolkit are free, open source and licensed
+
−for use under the X11/MIT License.
+
−
+
−JsDoc Toolkit is Copyright (c)2009 Michael Mathews <micmath@gmail.com>
+
−
+
−This program is free software; you can redistribute it and/or
+
−modify it under the terms below.
+
−
+
−Permission is hereby granted, free of charge, to any person obtaining
+
−a copy of this software and associated documentation files (the
+
−"Software"), to deal in the Software without restriction, including
+
−without limitation the rights to use, copy, modify, merge, publish,
+
−distribute, sublicense, and/or sell copies of the Software, and to
+
−permit persons to whom the Software is furnished to do so, subject to
+
−the following conditions: The above copyright notice and this
+
−permission notice must be included in all copies or substantial
+
−portions of the Software.
+
−
+
−THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+
−EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+
−MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
+
−IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
+
−CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
+
−TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
+
−SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.