| 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. |