codesite-noreply at google.com
2009-Aug-17 00:18 UTC
[Mapstraction] [mapstraction] r18 committed - Got mxn.js and mxn.core.js linting....
Revision: 18
Author: dezfowler
Date: Sun Aug 16 17:18:10 2009
Log: Got mxn.js and mxn.core.js linting.
Added an ant build process (lint, doc, min, license).
http://code.google.com/p/mapstraction/source/detail?r=18
Added:
/trunk/build.xml
/trunk/license.js
/trunk/tools/ant-contrib
/trunk/tools/ant-contrib/ant-contrib-1.0b3.jar
/trunk/tools/jsdoc-toolkit
/trunk/tools/jsdoc-toolkit/README.txt
/trunk/tools/jsdoc-toolkit/app
/trunk/tools/jsdoc-toolkit/app/frame
/trunk/tools/jsdoc-toolkit/app/frame/Chain.js
/trunk/tools/jsdoc-toolkit/app/frame/Dumper.js
/trunk/tools/jsdoc-toolkit/app/frame/Hash.js
/trunk/tools/jsdoc-toolkit/app/frame/Link.js
/trunk/tools/jsdoc-toolkit/app/frame/Namespace.js
/trunk/tools/jsdoc-toolkit/app/frame/Opt.js
/trunk/tools/jsdoc-toolkit/app/frame/Reflection.js
/trunk/tools/jsdoc-toolkit/app/frame/String.js
/trunk/tools/jsdoc-toolkit/app/frame/Testrun.js
/trunk/tools/jsdoc-toolkit/app/frame.js
/trunk/tools/jsdoc-toolkit/app/handlers
/trunk/tools/jsdoc-toolkit/app/handlers/FOODOC.js
/trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC
/trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/DomReader.js
/trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/XMLDoc.js
/trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/XMLParse.js
/trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC.js
/trunk/tools/jsdoc-toolkit/app/lib
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/DocComment.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/DocTag.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/JsDoc.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/JsPlate.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Lang.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Parser.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/PluginManager.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Symbol.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/SymbolSet.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TextStream.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Token.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TokenReader.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TokenStream.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Util.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Walker.js
/trunk/tools/jsdoc-toolkit/app/lib/JSDOC.js
/trunk/tools/jsdoc-toolkit/app/main.js
/trunk/tools/jsdoc-toolkit/app/plugins
/trunk/tools/jsdoc-toolkit/app/plugins/commentSrcJson.js
/trunk/tools/jsdoc-toolkit/app/plugins/frameworkPrototype.js
/trunk/tools/jsdoc-toolkit/app/plugins/functionCall.js
/trunk/tools/jsdoc-toolkit/app/plugins/publishSrcHilite.js
/trunk/tools/jsdoc-toolkit/app/plugins/symbolLink.js
/trunk/tools/jsdoc-toolkit/app/plugins/tagParamConfig.js
/trunk/tools/jsdoc-toolkit/app/plugins/tagSynonyms.js
/trunk/tools/jsdoc-toolkit/app/run.js
/trunk/tools/jsdoc-toolkit/app/t
/trunk/tools/jsdoc-toolkit/app/t/TestDoc.js
/trunk/tools/jsdoc-toolkit/app/t/runner.js
/trunk/tools/jsdoc-toolkit/app/test
/trunk/tools/jsdoc-toolkit/app/test/addon.js
/trunk/tools/jsdoc-toolkit/app/test/anon_inner.js
/trunk/tools/jsdoc-toolkit/app/test/augments.js
/trunk/tools/jsdoc-toolkit/app/test/augments2.js
/trunk/tools/jsdoc-toolkit/app/test/borrows.js
/trunk/tools/jsdoc-toolkit/app/test/borrows2.js
/trunk/tools/jsdoc-toolkit/app/test/config.js
/trunk/tools/jsdoc-toolkit/app/test/constructs.js
/trunk/tools/jsdoc-toolkit/app/test/encoding.js
/trunk/tools/jsdoc-toolkit/app/test/encoding_other.js
/trunk/tools/jsdoc-toolkit/app/test/event.js
/trunk/tools/jsdoc-toolkit/app/test/functions_anon.js
/trunk/tools/jsdoc-toolkit/app/test/functions_nested.js
/trunk/tools/jsdoc-toolkit/app/test/global.js
/trunk/tools/jsdoc-toolkit/app/test/globals.js
/trunk/tools/jsdoc-toolkit/app/test/ignore.js
/trunk/tools/jsdoc-toolkit/app/test/inner.js
/trunk/tools/jsdoc-toolkit/app/test/jsdoc_test.js
/trunk/tools/jsdoc-toolkit/app/test/lend.js
/trunk/tools/jsdoc-toolkit/app/test/memberof.js
/trunk/tools/jsdoc-toolkit/app/test/memberof_constructor.js
/trunk/tools/jsdoc-toolkit/app/test/name.js
/trunk/tools/jsdoc-toolkit/app/test/namespace_nested.js
/trunk/tools/jsdoc-toolkit/app/test/nocode.js
/trunk/tools/jsdoc-toolkit/app/test/oblit_anon.js
/trunk/tools/jsdoc-toolkit/app/test/overview.js
/trunk/tools/jsdoc-toolkit/app/test/param_inline.js
/trunk/tools/jsdoc-toolkit/app/test/params_optional.js
/trunk/tools/jsdoc-toolkit/app/test/prototype.js
/trunk/tools/jsdoc-toolkit/app/test/prototype_nested.js
/trunk/tools/jsdoc-toolkit/app/test/prototype_oblit.js
/trunk/tools/jsdoc-toolkit/app/test/prototype_oblit_constructor.js
/trunk/tools/jsdoc-toolkit/app/test/public.js
/trunk/tools/jsdoc-toolkit/app/test/scripts
/trunk/tools/jsdoc-toolkit/app/test/scripts/code.js
/trunk/tools/jsdoc-toolkit/app/test/scripts/notcode.txt
/trunk/tools/jsdoc-toolkit/app/test/shared.js
/trunk/tools/jsdoc-toolkit/app/test/shared2.js
/trunk/tools/jsdoc-toolkit/app/test/shortcuts.js
/trunk/tools/jsdoc-toolkit/app/test/static_this.js
/trunk/tools/jsdoc-toolkit/app/test/synonyms.js
/trunk/tools/jsdoc-toolkit/app/test/tosource.js
/trunk/tools/jsdoc-toolkit/app/test/variable_redefine.js
/trunk/tools/jsdoc-toolkit/app/test.js
/trunk/tools/jsdoc-toolkit/changes.txt
/trunk/tools/jsdoc-toolkit/conf
/trunk/tools/jsdoc-toolkit/conf/sample.conf
/trunk/tools/jsdoc-toolkit/java
/trunk/tools/jsdoc-toolkit/java/build.xml
/trunk/tools/jsdoc-toolkit/java/build_1.4.xml
/trunk/tools/jsdoc-toolkit/java/classes
/trunk/tools/jsdoc-toolkit/java/classes/js.jar
/trunk/tools/jsdoc-toolkit/java/src
/trunk/tools/jsdoc-toolkit/java/src/JsDebugRun.java
/trunk/tools/jsdoc-toolkit/java/src/JsRun.java
/trunk/tools/jsdoc-toolkit/jsdebug.jar
/trunk/tools/jsdoc-toolkit/jsrun.jar
/trunk/tools/jsdoc-toolkit/jsrun.sh
/trunk/tools/jsdoc-toolkit/mxn.conf
/trunk/tools/jsdoc-toolkit/templates
/trunk/tools/jsdoc-toolkit/templates/jsdoc
/trunk/tools/jsdoc-toolkit/templates/jsdoc/allclasses.tmpl
/trunk/tools/jsdoc-toolkit/templates/jsdoc/allfiles.tmpl
/trunk/tools/jsdoc-toolkit/templates/jsdoc/class.tmpl
/trunk/tools/jsdoc-toolkit/templates/jsdoc/index.tmpl
/trunk/tools/jsdoc-toolkit/templates/jsdoc/publish.js
/trunk/tools/jsdoc-toolkit/templates/jsdoc/static
/trunk/tools/jsdoc-toolkit/templates/jsdoc/static/default.css
/trunk/tools/jsdoc-toolkit/templates/jsdoc/static/header.html
/trunk/tools/jsdoc-toolkit/templates/jsdoc/static/index.html
/trunk/tools/jsdoc-toolkit/templates/jsdoc/symbol.tmpl
/trunk/tools/jslint
/trunk/tools/jslint/jslint.js
/trunk/tools/rhino
/trunk/tools/rhino/js.jar
/trunk/tools/yui-compressor
/trunk/tools/yui-compressor/yuicompressor-2.4.2.jar
Modified:
/trunk/source/mxn.(provider).core.js
/trunk/source/mxn.core.js
/trunk/source/mxn.google.core.js
/trunk/source/mxn.js
/trunk/source/mxn.yahoo.core.js
======================================--- /dev/null
+++ /trunk/build.xml Sun Aug 16 17:18:10 2009
@@ -0,0 +1,101 @@
+<?xml version="1.0"?>
+<project name="mapstraction" default="build">
+ <taskdef resource="net/sf/antcontrib/antlib.xml">
+ <classpath>
+ <pathelement
location="tools/ant-contrib/ant-contrib-1.0b3.jar"/>
+ </classpath>
+ </taskdef>
+
+ <!-- set global properties for this build -->
+ <property name="source" location="source"/>
+ <property name="build.base" location="build"/>
+ <property name="build.major" value="2"/>
+ <property name="build.minor" value="0"/>
+
+ <target name="build">
+ <!-- generate build number -->
+ <buildnumber/>
+ <tstamp>
+ <format property="YEAR" pattern="yyyy"/>
+ </tstamp>
+ <property name="build.ver"
value="${build.major}.${build.minor}.${build.number}"/>
+ <property name="build.dir"
location="${build.base}/${build.ver}"/>
+
+ <!-- make our build directory -->
+ <mkdir dir="${build.dir}"/>
+
+ <!-- copy our sources in -->
+ <echo>--- COPY SOURCES ---</echo>
+ <copy todir="${build.dir}" overwrite="true"
flatten="true">
+ <resources>
+ <file file="${source}/mxn.js"/>
+ <file file="${source}/mxn.core.js"/>
+ <file file="${source}/mxn.(provider).core.js"/>
+ <file file="${source}/mxn.cloudmade.core.js"/>
+ <file file="${source}/mxn.google.core.js"/>
+ <file file="${source}/mxn.microsoft.core.js"/>
+ <file file="${source}/mxn.yahoo.core.js"/>
+ </resources>
+ </copy>
+
+ <!-- lint our sources -->
+ <echo>--- LINT ---</echo>
+
+ <!-- Hopefully get the whole lot linting eventually
+ <java jar="tools/rhino/js.jar" fork="true"
failonerror="true">
+ <arg value="tools/jslint/jslint.js"/>
+ <arg value="${build.dir}/*.js"/>
+ </java>
+ -->
+
+ <java jar="tools/rhino/js.jar" fork="true"
failonerror="true">
+ <arg value="tools/jslint/jslint.js"/>
+ <arg value="${build.dir}/mxn.js"/>
+ </java>
+ <java jar="tools/rhino/js.jar" fork="true"
failonerror="true">
+ <arg value="tools/jslint/jslint.js"/>
+ <arg value="${build.dir}/mxn.core.js"/>
+ </java>
+
+ <!-- document our sources -->
+ <echo>--- DOC ---</echo>
+ <java jar="tools/jsdoc-toolkit/jsrun.jar" fork="true"
failonerror="true">
+ <arg value="tools/jsdoc-toolkit/app/run.js"/>
+ <arg value="${build.dir}/mxn.js"/>
+ <arg value="${build.dir}/mxn.core.js"/>
+ <arg value="-c=tools/jsdoc-toolkit/mxn.conf"/>
+ <arg value="-d=${build.dir}/docs"/>
+ </java>
+
+ <!-- minify our sources -->
+ <echo>--- MIN ---</echo>
+ <for param="file">
+ <path>
+ <fileset dir="${build.dir}" includes="*.js"/>
+ </path>
+ <sequential>
+ <propertyregex override="yes" property="minfile"
input="@{file}"
regexp=".*[\/\\]([a-z\.\(\)]+)\.js" replace="\1-min.js"/>
+ <java jar="tools/yui-compressor/yuicompressor-2.4.2.jar"
args="-o
${build.dir}\${minfile} @{file}" fork="true"
failonerror="true"/>
+ </sequential>
+ </for>
+
+ <!-- prepend our copyright and license notice -->
+ <echo>--- COPYRIGHT ---</echo>
+ <for param="file">
+ <path>
+ <fileset dir="${build.dir}" includes="*.js"/>
+ </path>
+ <sequential>
+ <concat destfile="${build.dir}\temp.t">
+ <header file="license.js"/>
+ <fileset file="@{file}"/>
+ <filterchain>
+ <expandproperties/>
+ </filterchain>
+ </concat>
+ <move file="${build.dir}\temp.t" tofile="@{file}"
overwrite="true"/>
+ </sequential>
+ </for>
+
+ </target>
+</project>
======================================--- /dev/null
+++ /trunk/license.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,12 @@
+/*
+Copyright (c) ${YEAR} Tom Carden, Steve Coast, Mikel Maron, Andrew Turner,
Henri Bergius, Rob Moran, Derek Fowler
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are met:
+
+ * Redistributions of source code must retain the above copyright notice,
this list of conditions and the following disclaimer.
+ * Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
+ * Neither the name of the Mapstraction nor the names of its contributors
may be used to endorse or promote products derived from this software
without specific prior written permission.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR
CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
======================================--- /dev/null
+++ /trunk/tools/ant-contrib/ant-contrib-1.0b3.jar Sun Aug 16 17:18:10 2009
Binary file, no diff available.
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/README.txt Sun Aug 16 17:18:10 2009
@@ -0,0 +1,186 @@
+=====================================================================+
+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 at 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.
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Chain.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,102 @@
+/**@constructor*/
+function ChainNode(object, link) {
+ this.value = object;
+ this.link = link; // describes this node''s relationship to the
previous
node
+}
+
+/**@constructor*/
+function Chain(valueLinks) {
+ this.nodes = [];
+ this.cursor = -1;
+
+ if (valueLinks && valueLinks.length > 0) {
+ this.push(valueLinks[0], "//");
+ for (var i = 1, l = valueLinks.length; i < l; i+=2) {
+ this.push(valueLinks[i+1], valueLinks[i]);
+ }
+ }
+}
+
+Chain.prototype.push = function(o, link) {
+ if (this.nodes.length > 0 && link) this.nodes.push(new ChainNode(o,
link));
+ else this.nodes.push(new ChainNode(o));
+}
+
+Chain.prototype.unshift = function(o, link) {
+ if (this.nodes.length > 0 && link) this.nodes[0].link = link;
+ this.nodes.unshift(new ChainNode(o));
+ this.cursor++;
+}
+
+Chain.prototype.get = function() {
+ if (this.cursor < 0 || this.cursor > this.nodes.length-1) return null;
+ return this.nodes[this.cursor];
+}
+
+Chain.prototype.first = function() {
+ this.cursor = 0;
+ return this.get();
+}
+
+Chain.prototype.last = function() {
+ this.cursor = this.nodes.length-1;
+ return this.get();
+}
+
+Chain.prototype.next = function() {
+ this.cursor++;
+ return this.get();
+}
+
+Chain.prototype.prev = function() {
+ this.cursor--;
+ return this.get();
+}
+
+Chain.prototype.toString = function() {
+ var string = "";
+ for (var i = 0, l = this.nodes.length; i < l; i++) {
+ if (this.nodes[i].link) string += "
-("+this.nodes[i].link+")-> ";
+ string += this.nodes[i].value.toString();
+ }
+ return string;
+}
+
+Chain.prototype.joinLeft = function() {
+ var result = "";
+ for (var i = 0, l = this.cursor; i < l; i++) {
+ if (result && this.nodes[i].link) result += this.nodes[i].link;
+ result += this.nodes[i].value.toString();
+ }
+ return result;
+}
+
+
+/* USAGE:
+
+var path = "one/two/three.four/five-six";
+var pathChain = new Chain(path.split(/([\/.-])/));
+print(pathChain);
+
+var lineage = new Chain();
+lineage.push("Port");
+lineage.push("Les", "son");
+lineage.push("Dawn", "daughter");
+lineage.unshift("Purdie", "son");
+
+print(lineage);
+
+// walk left
+for (var node = lineage.last(); node !== null; node = lineage.prev()) {
+ print("< "+node.value);
+}
+
+// walk right
+var node = lineage.first()
+while (node !== null) {
+ print(node.value);
+ node = lineage.next();
+ if (node && node.link) print("had a "+node.link+"
named");
+}
+
+*/
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Dumper.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,144 @@
+/**
+ * @class
+<pre>
+This is a lightly modified version of Kevin Jones'' JavaScript
+library Data.Dump. To download the original visit:
+ <a
href="http://openjsan.org/doc/k/ke/kevinj/Data/Dump/">http://openjsan.org/doc/k/ke/kevinj/Data/Dump/</a>
+
+AUTHORS
+
+The Data.Dump JavaScript module is written by Kevin Jones
+(kevinj at cpan.org), based on Data::Dump by Gisle Aas (gisle at aas.no),
+based on Data::Dumper by Gurusamy Sarathy (gsar at umich.edu).
+
+COPYRIGHT
+
+Copyright 2007 Kevin Jones. Copyright 1998-2000,2003-2004 Gisle Aas.
+Copyright 1996-1998 Gurusamy Sarathy.
+
+This program is free software; you can redistribute it and/or modify
+it under the terms of the Perl Artistic License
+
+See http://www.perl.com/perl/misc/Artistic.html
+</pre>
+ * @static
+ */
+Dumper = {
+ /** @param [...] The objects to dump. */
+ dump: function () {
+ if (arguments.length > 1)
+ return this._dump(arguments);
+ else if (arguments.length == 1)
+ return this._dump(arguments[0]);
+ else
+ return "()";
+ },
+
+ _dump: function (obj) {
+ if (typeof obj == ''undefined'') return
''undefined'';
+ var out;
+ if (obj.serialize) { return obj.serialize(); }
+ var type = this._typeof(obj);
+ if (obj.circularReference) obj.circularReference++;
+ switch (type) {
+ case ''circular'':
+ out = "{ //circularReference\n}";
+ break;
+ case ''object'':
+ var pairs = new Array;
+
+ for (var prop in obj) {
+ if (prop != "circularReference" &&
obj.hasOwnProperty(prop)) { //hide
inherited properties
+ pairs.push(prop + '': '' + this._dump(obj[prop]));
+ }
+ }
+
+ out = ''{'' + this._format_list(pairs) +
''}'';
+ break;
+
+ case ''string'':
+ for (var prop in Dumper.ESC) {
+ if (Dumper.ESC.hasOwnProperty(prop)) {
+ obj = obj.replace(prop, Dumper.ESC[prop]);
+ }
+ }
+
+ // Escape UTF-8 Strings
+ if (obj.match(/^[\x00-\x7f]*$/)) {
+ out = ''"'' + obj.replace(/\"/g,
"\\\"").replace(/([\n\r]+)/g, "\\$1")
+ ''"'';
+ }
+ else {
+ out = "unescape(''"+escape(obj)+"'')";
+ }
+ break;
+
+ case ''array'':
+ var elems = new Array;
+
+ for (var i=0; i<obj.length; i++) {
+ elems.push( this._dump(obj[i]) );
+ }
+
+ out = ''['' + this._format_list(elems) +
'']'';
+ break;
+
+ case ''date'':
+ // firefox returns GMT strings from toUTCString()...
+ var utc_string = obj.toUTCString().replace(/GMT/,''UTC'');
+ out = ''new Date("'' + utc_string +
''")'';
+ break;
+
+ case ''element'':
+ // DOM element
+ out = this._dump_dom(obj);
+ break;
+
+ default:
+ out = obj;
+ }
+
+ out = String(out).replace(/\n/g, ''\n '');
+ out = out.replace(/\n (.*)$/,"\n$1");
+
+ return out;
+ },
+
+ _format_list: function (list) {
+ if (!list.length) return '''';
+ var nl = list.toString().length > 60 ? ''\n'' : ''
'';
+ return nl + list.join('','' + nl) + nl;
+ },
+
+ _typeof: function (obj) {
+ if (obj && obj.circularReference && obj.circularReference
> 1)
return ''circular'';
+ if (Array.prototype.isPrototypeOf(obj)) return ''array'';
+ if (Date.prototype.isPrototypeOf(obj)) return ''date'';
+ if (typeof obj.nodeType != ''undefined'') return
''element'';
+ return typeof(obj);
+ },
+
+ _dump_dom: function (obj) {
+ return ''"'' + Dumper.nodeTypes[obj.nodeType] +
''"'';
+ }
+};
+
+Dumper.ESC = {
+ "\t": "\\t",
+ "\n": "\\n",
+ "\f": "\\f"
+};
+
+Dumper.nodeTypes = {
+ 1: "ELEMENT_NODE",
+ 2: "ATTRIBUTE_NODE",
+ 3: "TEXT_NODE",
+ 4: "CDATA_SECTION_NODE",
+ 5: "ENTITY_REFERENCE_NODE",
+ 6: "ENTITY_NODE",
+ 7: "PROCESSING_INSTRUCTION_NODE",
+ 8: "COMMENT_NODE",
+ 9: "DOCUMENT_NODE",
+ 10: "DOCUMENT_TYPE_NODE",
+ 11: "DOCUMENT_FRAGMENT_NODE",
+ 12: "NOTATION_NODE"
+};
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Hash.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,84 @@
+/**
+ @constructor
+ @example
+ var _index = new Hash();
+ _index.set("a", "apple");
+ _index.set("b", "blue");
+ _index.set("c", "coffee");
+
+ for (var p = _index.first(); p; p = _index.next()) {
+ print(p.key+" is for "+p.value);
+ }
+
+ */
+var Hash = function() {
+ this._map = {};
+ this._keys = [];
+ this._vals = [];
+ this.reset();
+}
+
+Hash.prototype.set = function(k, v) {
+ if (k != "") {
+ this._keys.push(k);
+ this._map["="+k] = this._vals.length;
+ this._vals.push(v);
+ }
+}
+
+Hash.prototype.replace = function(k, k2, v) {
+ if (k == k2) return;
+
+ var offset = this._map["="+k];
+ this._keys[offset] = k2;
+ if (typeof v != "undefined") this._vals[offset] = v;
+ this._map["="+k2] = offset;
+ delete(this._map["="+k]);
+}
+
+Hash.prototype.drop = function(k) {
+ if (k != "") {
+ var offset = this._map["="+k];
+ this._keys.splice(offset, 1);
+ this._vals.splice(offset, 1);
+ delete(this._map["="+k]);
+ for (var p in this._map) {
+ if (this._map[p] >= offset) this._map[p]--;
+ }
+ if (this._cursor >= offset && this._cursor > 0) this._cursor--;
+ }
+}
+
+Hash.prototype.get = function(k) {
+ if (k != "") {
+ return this._vals[this._map["="+k]];
+ }
+}
+
+Hash.prototype.keys = function() {
+ return this._keys;
+}
+
+Hash.prototype.hasKey = function(k) {
+ if (k != "") {
+ return (typeof this._map["="+k] != "undefined");
+ }
+}
+
+Hash.prototype.values = function() {
+ return this._vals;
+}
+
+Hash.prototype.reset = function() {
+ this._cursor = 0;
+}
+
+Hash.prototype.first = function() {
+ this.reset();
+ return this.next();
+}
+
+Hash.prototype.next = function() {
+ if (this._cursor++ < this._keys.length)
+ return {key: this._keys[this._cursor-1], value:
this._vals[this._cursor-1]};
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Link.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,148 @@
+/** Handle the creation of HTML links to documented symbols.
+ @constructor
+*/
+function Link() {
+ this.alias = "";
+ this.src = "";
+ this.file = "";
+ this.text = "";
+ this.innerName = "";
+ this.classLink = false;
+ this.targetName = "";
+
+ this.target = function(targetName) {
+ if (defined(targetName)) this.targetName = targetName;
+ return this;
+ }
+ this.inner = function(inner) {
+ if (defined(inner)) this.innerName = inner;
+ return this;
+ }
+ this.withText = function(text) {
+ if (defined(text)) this.text = text;
+ return this;
+ }
+ this.toSrc = function(filename) {
+ if (defined(filename)) this.src = filename;
+ return this;
+ }
+ this.toSymbol = function(alias) {
+ if (defined(alias)) this.alias = new String(alias);
+ return this;
+ }
+ this.toClass = function(alias) {
+ this.classLink = true;
+ return this.toSymbol(alias);
+ }
+ this.toFile = function(file) {
+ if (defined(file)) this.file = file;
+ return this;
+ }
+
+ this.toString = function() {
+ var linkString;
+ var thisLink = this;
+
+ if (this.alias) {
+ linkString = this.alias.replace(/(^|[^a-z$0-9_#.:^-])([|
a-z$0-9_#.:^-]+)($|[^a-z$0-9_#.:^-])/i,
+ function(match, prematch, symbolName, postmatch) {
+ var symbolNames = symbolName.split("|");
+ var links = [];
+ for (var i = 0, l = symbolNames.length; i < l; i++) {
+ thisLink.alias = symbolNames[i];
+ links.push(thisLink._makeSymbolLink(symbolNames[i]));
+ }
+ return prematch+links.join("|")+postmatch;
+ }
+ );
+ }
+ else if (this.src) {
+ linkString = thisLink._makeSrcLink(this.src);
+ }
+ else if (this.file) {
+ linkString = thisLink._makeFileLink(this.file);
+ }
+
+ return linkString;
+ }
+}
+
+/** prefixed for hashes */
+Link.hashPrefix = "";
+
+/** Appended to the front of relative link paths. */
+Link.base = "";
+
+Link.symbolNameToLinkName = function(symbol) {
+ var linker = "";
+ if (symbol.isStatic) linker = ".";
+ else if (symbol.isInner) linker = "-";
+
+ return Link.hashPrefix+linker+symbol.name;
+}
+
+/** Create a link to a snother symbol. */
+Link.prototype._makeSymbolLink = function(alias) {
+ var linkBase = Link.base+publish.conf.symbolsDir;
+ var linkTo = Link.symbolSet.getSymbol(alias);
+ var linkPath;
+ var target = (this.targetName)? "
target=\""+this.targetName+"\"" : "";
+
+ // is it an internal link?
+ if (alias.charAt(0) == "#") var linkPath = alias;
+
+ // if there is no symbol by that name just return the name unaltered
+ else if (!linkTo) return this.text || alias;
+
+ // it''s a symbol in another file
+ else {
+
+ if (!linkTo.is("CONSTRUCTOR") && !linkTo.isNamespace) { //
it''s a method
or property
+ if (linkTo.isEvent) {
+ linkPath = escape(linkTo.memberOf) || "_global_";
+ linkPath += publish.conf.ext + "#event:" +
Link.symbolNameToLinkName(linkTo);
+ }
+ else {
+ linkPath = escape(linkTo.memberOf) || "_global_";
+ linkPath += publish.conf.ext + "#" +
Link.symbolNameToLinkName(linkTo);
+ }
+ }
+ else {
+ linkPath = escape(linkTo.alias);
+ linkPath += publish.conf.ext;// + (this.classLink?
"":"#" +
Link.hashPrefix + "constructor");
+ }
+ linkPath = linkBase + linkPath
+ }
+
+ var linkText = this.text || alias;
+
+ var link = {linkPath: linkPath, linkText: linkText};
+
+ if (typeof JSDOC.PluginManager != "undefined") {
+ JSDOC.PluginManager.run("onSymbolLink", link);
+ }
+
+ return "<a
href=\""+link.linkPath+"\""+target+">"+link.linkText+"</a>";
+}
+
+/** Create a link to a source file. */
+Link.prototype._makeSrcLink = function(srcFilePath) {
+ var target = (this.targetName)? "
target=\""+this.targetName+"\"" : "";
+
+ // transform filepath into a filename
+ var srcFile =
srcFilePath.replace(/\.\.?[\\\/]/g, "").replace(/[:\\\/]/g,
"_");
+ var outFilePath = Link.base + publish.conf.srcDir + srcFile +
publish.conf.ext;
+
+ if (!this.text) this.text = FilePath.fileName(srcFilePath);
+ return "<a
href=\""+outFilePath+"\""+target+">"+this.text+"</a>";
+}
+
+/** Create a link to a source file. */
+Link.prototype._makeFileLink = function(filePath) {
+ var target = (this.targetName)? "
target=\""+this.targetName+"\"" : "";
+
+ var outFilePath = Link.base + filePath;
+
+ if (!this.text) this.text = filePath;
+ return "<a
href=\""+outFilePath+"\""+target+">"+this.text+"</a>";
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Namespace.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,10 @@
+_global_ = this;
+
+function Namespace(name, f) {
+ var n = name.split(".");
+ for (var o = _global_, i = 0, l = n.length; i < l; i++) {
+ o = o[n[i]] = o[n[i]] || {};
+ }
+
+ if (f) f();
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Opt.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,134 @@
+/** @namespace */
+Opt = {
+ /**
+ * Get commandline option values.
+ * @param {Array} args Commandline arguments. Like
["-a=xml", "-b", "--class=new",
"--debug"]
+ * @param {object} optNames Map short names to long names. Like
{a:"accept", b:"backtrace", c:"class",
d:"debug"}.
+ * @return {object} Short names and values. Like {a:"xml", b:true,
c:"new", d:true}
+ */
+ get: function(args, optNames) {
+ var opt = {"_": []}; // the unnamed option allows multiple values
+ for (var i = 0; i < args.length; i++) {
+ var arg = new String(args[i]);
+ var name;
+ var value;
+ if (arg.charAt(0) == "-") {
+ if (arg.charAt(1) == "-") { // it''s a longname like
--foo
+ arg = arg.substring(2);
+ var m = arg.split("=");
+ name = m.shift();
+ value = m.shift();
+ if (typeof value == "undefined") value = true;
+
+ for (var n in optNames) { // convert it to a shortname
+ if (name == optNames[n]) {
+ name = n;
+ }
+ }
+ }
+ else { // it''s a shortname like -f
+ arg = arg.substring(1);
+ var m = arg.split("=");
+ name = m.shift();
+ value = m.shift();
+ if (typeof value == "undefined") value = true;
+
+ for (var n in optNames) { // find the matching key
+ if (name == n || name+''[]'' == n) {
+ name = n;
+ break;
+ }
+ }
+ }
+ if (name.match(/(.+)\[\]$/)) { // it''s an array type like n[]
+ name = RegExp.$1;
+ if (!opt[name]) opt[name] = [];
+ }
+
+ if (opt[name] && opt[name].push) {
+ opt[name].push(value);
+ }
+ else {
+ opt[name] = value;
+ }
+ }
+ else { // not associated with any optname
+ opt._.push(args[i]);
+ }
+ }
+ return opt;
+ }
+}
+
+/*t:
+ plan(11, "Testing Opt.");
+
+ is(
+ typeof Opt,
+ "object",
+ "Opt is an object."
+ );
+
+ is(
+ typeof Opt.get,
+ "function",
+ "Opt.get is a function."
+ );
+
+ var optNames = {a:"accept", b:"backtrace",
c:"class",
d:"debug", "e[]":"exceptions"};
+ var t_options =
Opt.get(["-a=xml", "-b", "--class=new",
"--debug", "-e=one", "-e=two", "foo",
"bar"],
optNames);
+
+ is(
+ t_options.a,
+ "xml",
+ "an option defined with a short name can be accessed by its short
name."
+ );
+
+ is(
+ t_options.b,
+ true,
+ "an option defined with a short name and no value are true."
+ );
+
+ is(
+ t_options.c,
+ "new",
+ "an option defined with a long name can be accessed by its short
name."
+ );
+
+ is(
+ t_options.d,
+ true,
+ "an option defined with a long name and no value are true."
+ );
+
+ is(
+ typeof t_options.e,
+ "object",
+ "an option that can accept multiple values is defined."
+ );
+
+ is(
+ t_options.e.length,
+ 2,
+ "an option that can accept multiple values can have more than one
value."
+ );
+
+ is(
+ t_options.e[1],
+ "two",
+ "an option that can accept multiple values can be accessed as an
array."
+ );
+
+ is(
+ typeof t_options._,
+ "object",
+ "the property ''_'' is defined for unnamed
options."
+ );
+
+ is(
+ t_options._[0],
+ "foo",
+ "the property ''_'' can be accessed as an array."
+ );
+ */
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Reflection.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,26 @@
+/**@constructor*/
+function Reflection(obj) {
+ this.obj = obj;
+}
+
+Reflection.prototype.getConstructorName = function() {
+ if (this.obj.constructor.name) return this.obj.constructor.name;
+ var src = this.obj.constructor.toSource();
+ var name = src.substring(name.indexOf("function")+8,
src.indexOf(''('')).replace(/ /g,'''');
+ return name;
+}
+
+Reflection.prototype.getMethod = function(name) {
+ for (var p in this.obj) {
+ if (p == name && typeof(this.obj[p]) == "function") return
this.obj[p];
+ }
+ return null;
+}
+
+Reflection.prototype.getParameterNames = function() {
+ var src = this.obj.toSource();
+ src = src.substring(
+ src.indexOf("(", 8)+1, src.indexOf(")")
+ );
+ return src.split(/, ?/);
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/String.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,93 @@
+/**
+ @name String
+ @class Additions to the core string object.
+*/
+
+/** @author Steven Levithan, released as public domain. */
+String.prototype.trim = function() {
+ var str = this.replace(/^\s+/, '''');
+ for (var i = str.length - 1; i >= 0; i--) {
+ if (/\S/.test(str.charAt(i))) {
+ str = str.substring(0, i + 1);
+ break;
+ }
+ }
+ return str;
+}
+/*t:
+ plan(6, "Testing String.prototype.trim.");
+
+ var s = " a bc ".trim();
+ is(s, "a bc", "multiple spaces front and back are
trimmed.");
+
+ s = "a bc\n\n".trim();
+ is(s, "a bc", "newlines only in back are trimmed.");
+
+ s = "\ta bc".trim();
+ is(s, "a bc", "tabs only in front are trimmed.");
+
+ s = "\n \t".trim();
+ is(s, "", "an all-space string is trimmed to empty.");
+
+ s = "a b\nc".trim();
+ is(s, "a b\nc", "a string with no spaces in front or back is
trimmed to
itself.");
+
+ s = "".trim();
+ is(s, "", "an empty string is trimmed to empty.");
+
+*/
+
+String.prototype.balance = function(open, close) {
+ var i = 0;
+ while (this.charAt(i) != open) {
+ if (i == this.length) return [-1, -1];
+ i++;
+ }
+
+ var j = i+1;
+ var balance = 1;
+ while (j < this.length) {
+ if (this.charAt(j) == open) balance++;
+ if (this.charAt(j) == close) balance--;
+ if (balance == 0) break;
+ j++;
+ if (j == this.length) return [-1, -1];
+ }
+
+ return [i, j];
+}
+/*t:
+ plan(16, "Testing String.prototype.balance.");
+
+ var s = "{abc}".balance("{","}");
+ is(s[0], 0, "opener in first is found.");
+ is(s[1], 4, "closer in last is found.");
+
+ s = "ab{c}de".balance("{","}");
+ is(s[0], 2, "opener in middle is found.");
+ is(s[1], 4, "closer in middle is found.");
+
+ s = "a{b{c}de}f".balance("{","}");
+ is(s[0], 1, "nested opener is found.");
+ is(s[1], 8, "nested closer is found.");
+
+ s = "{}".balance("{","}");
+ is(s[0], 0, "opener with no content is found.");
+ is(s[1], 1, "closer with no content is found.");
+
+ s = "".balance("{","}");
+ is(s[0], -1, "empty string opener is -1.");
+ is(s[1], -1, "empty string closer is -1.");
+
+ s = "{abc".balance("{","}");
+ is(s[0], -1, "opener with no closer returns -1.");
+ is(s[1], -1, "no closer returns -1.");
+
+ s = "abc".balance("{","}");
+ is(s[0], -1, "no opener or closer returns -1 for opener.");
+ is(s[1], -1, "no opener or closer returns -1 for closer.");
+
+ s = "a<bc}de".balance("<","}");
+ is(s[0], 1, "unmatching opener is found.");
+ is(s[1], 4, "unmatching closer is found.");
+*/
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame/Testrun.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,129 @@
+/**
+ * @fileOverview
+ * @name JsTestrun
+ * @author Michael Mathews micmath at gmail.com
+ * @url $HeadURL:
https://jsdoc-toolkit.googlecode.com/svn/trunk/jsdoc-toolkit/app/frame/Testrun.js
$
+ * @revision $Id: Testrun.js 418 2008-01-15 21:40:33Z micmath $
+ * @license <a
href="http://en.wikipedia.org/wiki/MIT_License">X11/MIT
License</a>
+ * (See the accompanying README file for full details.)
+ */
+
+/**
+ Yet another unit testing tool for JavaScript.
+ @author Michael Mathews <a
href="mailto:micmath at gmail.com">micmath at gmail.com</a>
+ @param {object} testCases Properties are testcase names, values are
functions to execute as tests.
+*/
+function testrun(testCases) {
+ var ran = 0;
+ for (t in testCases) {
+ var result = testCases[t]();
+ ran++;
+ }
+
+ return
testrun.reportOut+"-------------------------------\n"+((testrun.fails>0)?
":(
Failed "+testrun.fails+"/" : ":) Passed all
")+testrun.count+"
test"+((testrun.count == 1)? "":"s")+".\n";
+}
+
+
+testrun.count = 0;
+testrun.current = null;
+testrun.passes = 0;
+testrun.fails = 0;
+testrun.reportOut = "";
+
+/** @private */
+testrun.report = function(text) {
+ testrun.reportOut += text+"\n";
+}
+
+/**
+ Check if test evaluates to true.
+ @param {string} test To be evaluated.
+ @param {string} message Optional. To be displayed in the report.
+ @return {boolean} True if the string test evaluates to true.
+*/
+ok = function(test, message) {
+ testrun.count++;
+
+ var result;
+ try {
+ result = eval(test);
+
+ if (result) {
+ testrun.passes++;
+ testrun.report(" OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ }
+ else {
+ testrun.fails++;
+ testrun.report("NOT OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ }
+ }
+ catch(e) {
+ testrun.fails++
+ testrun.report("NOT OK "+testrun.count+" - "+((message !=
null)?
message : ""));
+
+ }
+}
+
+/**
+ Check if test is same as expected.
+ @param {string} test To be evaluated.
+ @param {string} expected
+ @param {string} message Optional. To be displayed in the report.
+ @return {boolean} True if (test == expected). Note that the comparison is
not a strict equality check.
+*/
+is = function(test, expected, message) {
+ testrun.count++;
+
+ var result;
+ try {
+ result = eval(test);
+
+ if (result == expected) {
+ testrun.passes++
+ testrun.report(" OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ }
+ else {
+ testrun.fails++
+ testrun.report("NOT OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ testrun.report("expected: "+expected);
+ testrun.report(" got: "+result);
+ }
+ }
+ catch(e) {
+ testrun.fails++
+ testrun.report("NOT OK "+testrun.count+" - "+((message !=
null)?
message : ""));
+ testrun.report("expected: "+expected);
+ testrun.report(" got: "+result);}
+}
+
+/**
+ Check if test matches pattern.
+ @param {string} test To be evaluated.
+ @param {string} pattern Used to create a RegExp.
+ @param {string} message Optional. To be displayed in the report.
+ @return {boolean} True if test matches pattern.
+*/
+like = function(test, pattern, message) {
+ testrun.count++;
+
+ var result;
+ try {
+ result = eval(test);
+ var rgx = new RegExp(pattern);
+
+ if (rgx.test(result)) {
+ testrun.passes++
+ testrun.report(" OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ }
+ else {
+ testrun.fails++
+ testrun.report("NOT OK "+testrun.count+" - "+((message
!= null)?
message : ""));
+ testrun.report(" this: "+result);
+ testrun.report("is not like: "+pattern);
+ }
+ }
+ catch(e) {
+ testrun.fails++
+ testrun.report("NOT OK "+testrun.count+" - "+((message !=
null)?
message : ""));
+ }
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/frame.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,33 @@
+IO.include("frame/Opt.js");
+IO.include("frame/Chain.js");
+IO.include("frame/Link.js");
+IO.include("frame/String.js");
+IO.include("frame/Hash.js");
+IO.include("frame/Namespace.js");
+//IO.include("frame/Reflection.js");
+
+/** A few helper functions to make life a little easier. */
+
+function defined(o) {
+ return (o !== undefined);
+}
+
+function copy(o) { // todo check for circular refs
+ if (o == null || typeof(o) != ''object'') return o;
+ var c = new o.constructor();
+ for(var p in o) c[p] = copy(o[p]);
+ return c;
+}
+
+function isUnique(arr) {
+ var l = arr.length;
+ for(var i = 0; i < l; i++ ) {
+ if (arr.lastIndexOf(arr[i]) > i) return false;
+ }
+ return true;
+}
+
+/** Returns the given string with all regex meta characters backslashed. */
+RegExp.escapeMeta = function(str) {
+ return str.replace(/([$^\\\/()|?+*\[\]{}.-])/g, "\\$1");
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/handlers/FOODOC.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,26 @@
+/**
+ This is the main container for the FOODOC handler.
+ @namespace
+*/
+FOODOC = {
+};
+
+/** The current version string of this application. */
+FOODOC.VERSION = "1.0";
+
+FOODOC.handle = function(srcFile, src) {
+ LOG.inform("Handling file ''" + srcFile +
"''");
+
+ return [
+ new JSDOC.Symbol(
+ "foo",
+ [],
+ "VIRTUAL",
+ new JSDOC.DocComment("/** This is a foo. */")
+ )
+ ];
+};
+
+FOODOC.publish = function(symbolgroup) {
+ LOG.inform("Publishing symbolgroup.");
+};
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/DomReader.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,159 @@
+LOG.inform("XMLDOC.DomReader loaded");
+
+XMLDOC.DomReader = function(root) {
+
+ this.dom = root;
+
+ /**
+ * The current node the reader is on
+ */
+ this.node = root;
+
+ /**
+ * Get the current node the reader is on
+ * @type XMLDOC.Parser.node
+ */
+ XMLDOC.DomReader.prototype.getNode = function() {
+ return this.node;
+ };
+
+ /**
+ * Set the node the reader should be positioned on.
+ * @param node {XMLDOC.Parser.node}
+ */
+ XMLDOC.DomReader.prototype.setNode = function(node) {
+ this.node = node;
+ };
+
+ /**
+ * A helper method to make sure the current node will
+ * never return null, unless null is passed as the root.
+ * @param step {String} An expression to evaluate - should return a
node or null
+ */
+ XMLDOC.DomReader.prototype.navigate = function(step) {
+ var n;
+ if ((n = step) != null)
+ {
+ this.node = n;
+ return this.node;
+ }
+ return null;
+ };
+
+ /**
+ * Get the root node of the current node''s document.
+ */
+ XMLDOC.DomReader.prototype.root = function() {
+ this.navigate(this.dom);
+ };
+
+ /**
+ * Get the parent of the current node.
+ */
+ XMLDOC.DomReader.prototype.parent = function() {
+ return this.navigate(this.node.parentNode());
+ };
+
+ /**
+ * Get the first child of the current node.
+ */
+ XMLDOC.DomReader.prototype.firstChild = function() {
+ return this.navigate(this.node.firstChild());
+ };
+
+ /**
+ * Get the last child of the current node.
+ */
+ XMLDOC.DomReader.prototype.lastChild = function() {
+ return this.navigate(this.node.lastChild());
+ };
+
+ /**
+ * Get the next sibling of the current node.
+ */
+ XMLDOC.DomReader.prototype.nextSibling = function() {
+ return this.navigate(this.node.nextSibling());
+ };
+
+ /**
+ * Get the previous sibling of the current node.
+ */
+ XMLDOC.DomReader.prototype.prevSibling = function() {
+ return this.navigate(this.node.prevSibling());
+ };
+
+
//==============================================================================================+
// Support methods
+
+ /**
+ * Walk the tree starting with the current node, calling the plug-in for
+ * each node visited. Each time the plug-in is called, the DomReader
+ * is passed as the only parameter. Use the {@link
XMLDOC.DomReader#getNode} method
+ * to access the current node. <i>This method uses a depth first
traversal pattern.</i>
+ *
+ * @param srcFile {String} The source file being evaluated
+ */
+ XMLDOC.DomReader.prototype.getSymbols = function(srcFile)
+ {
+ XMLDOC.DomReader.symbols = [];
+ XMLDOC.DomReader.currentFile = srcFile;
+ JSDOC.Symbol.srcFile = (srcFile || "");
+
+ if (defined(JSDOC.PluginManager)) {
+ JSDOC.PluginManager.run("onDomGetSymbols", this);
+ }
+
+ return XMLDOC.DomReader.symbols;
+ };
+
+ /**
+ * Find the node with the given name using a depth first traversal.
+ * Does not modify the DomReader''s current node.
+ *
+ * @param name {String} The name of the node to find
+ * @return the node that was found, or null if not found
+ */
+ XMLDOC.DomReader.prototype.findNode = function(name)
+ {
+ var findNode = null;
+
+ // Start at the current node and move into the subtree,
+ // looking for the node with the given name
+ function deeper(node, find)
+ {
+ var look = null;
+
+ if (node) {
+ if (node.name == find)
+ {
+ return node;
+ }
+
+ if (node.firstChild())
+ {
+ look = deeper(node.firstChild(), find);
+ }
+
+ if (!look && node.nextSibling())
+ {
+ look = deeper(node.nextSibling(), find);
+ }
+ }
+
+ return look;
+ }
+
+ return deeper(this.getNode().firstChild(), name);
+ };
+
+ /**
+ * Find the next node with the given name using a depth first traversal.
+ *
+ * @param name {String} The name of the node to find
+ */
+ XMLDOC.DomReader.prototype.findPreviousNode = function(name)
+ {
+ };
+
+};
+
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/XMLDoc.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,16 @@
+LOG.inform("XMLDOC.symbolize loaded");
+
+/**
+ * Convert the source file to a set of symbols
+ */
+XMLDOC.symbolize = function(srcFile, src) {
+
+ LOG.inform("Symbolizing file ''" + srcFile +
"''");
+
+ // XML files already have a defined structure, so we don''t need to
+ // do anything but parse them. The DOM reader can create a symbol
+ // table from the parsed XML.
+ var dr = new XMLDOC.DomReader(XMLDOC.Parser.parse(src));
+ return dr.getSymbols(srcFile);
+
+};
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC/XMLParse.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,292 @@
+LOG.inform("XMLDOC.Parser loaded");
+
+/**
+ * XML Parser object. Returns an {@link #XMLDOC.Parser.node} which is
+ * the root element of the parsed document.
+ * <p/>
+ * By default, this parser will only handle well formed XML. To
+ * allow the parser to handle HTML, set the
<tt>XMLDOC.Parser.strictMode</tt>
+ * variable to <tt>false</tt> before calling
<tt>XMLDOC.Parser.parse()</tt>.
+ * <p/>
+ * <i>Note: If you pass poorly formed XML, it will cause the parser to
throw
+ * an exception.</i>
+ *
+ * @author Brett Fattori (bfattori at fry.com)
+ * @author $Author: micmath $
+ * @version $Revision: 497 $
+ */
+XMLDOC.Parser = {};
+
+/**
+ * Strict mode setting. Setting this to false allows HTML-style source to
+ * be parsed. Normally, well formed XML has defined end tags, or empty
tags
+ * are properly formed. Default: <tt>true</tt>
+ * @type Boolean
+ */
+XMLDOC.Parser.strictMode = true;
+
+/**
+ * A node in an XML Document. Node types are ROOT, ELEMENT, COMMENT, PI,
and TEXT.
+ * @param parent {XMLDOC.Parser.node} The parent node
+ * @param name {String} The node name
+ * @param type {String} One of the types
+ */
+XMLDOC.Parser.node = function(parent, name, type)
+{
+ this.name = name;
+ this.type = type || "ELEMENT";
+ this.parent = parent;
+ this.charData = "";
+ this.attrs = {};
+ this.nodes = [];
+ this.cPtr = 0;
+
+ XMLDOC.Parser.node.prototype.getAttributeNames = function() {
+ var a = [];
+ for (var o in this.attrs)
+ {
+ a.push(o);
+ }
+
+ return a;
+ };
+
+ XMLDOC.Parser.node.prototype.getAttribute = function(attr) {
+ return this.attrs[attr];
+ };
+
+ XMLDOC.Parser.node.prototype.setAttribute = function(attr, val) {
+ this.attrs[attr] = val;
+ };
+
+ XMLDOC.Parser.node.prototype.getChild = function(idx) {
+ return this.nodes[idx];
+ };
+
+ XMLDOC.Parser.node.prototype.parentNode = function() {
+ return this.parent;
+ };
+
+ XMLDOC.Parser.node.prototype.firstChild = function() {
+ return this.nodes[0];
+ };
+
+ XMLDOC.Parser.node.prototype.lastChild = function() {
+ return this.nodes[this.nodes.length - 1];
+ };
+
+ XMLDOC.Parser.node.prototype.nextSibling = function() {
+ var p = this.parent;
+ if (p && (p.nodes.indexOf(this) + 1 != p.nodes.length))
+ {
+ return p.getChild(p.nodes.indexOf(this) + 1);
+ }
+ return null;
+ };
+
+ XMLDOC.Parser.node.prototype.prevSibling = function() {
+ var p = this.parent;
+ if (p && (p.nodes.indexOf(this) - 1 >= 0))
+ {
+ return p.getChild(p.nodes.indexOf(this) - 1);
+ }
+ return null;
+ };
+};
+
+/**
+ * Parse an XML Document from the specified source. The XML should be
+ * well formed, unless strict mode is disabled, then the parser will
+ * handle HTML-style XML documents.
+ * @param src {String} The source to parse
+ */
+XMLDOC.Parser.parse = function(src)
+{
+ var A = [];
+
+ // Normailize whitespace
+ A = src.split("\r\n");
+ src = A.join("\n");
+ A = src.split("\r");
+ src = A.join("\n");
+
+ // Remove XML and DOCTYPE specifier
+ src.replace(/<\?XML .*\?>/i, "");
+ src.replace(/<!DOCTYPE .*\>/i, "");
+
+ // The document is the root node and cannot be modified or removed
+ var doc = new XMLDOC.Parser.node(null, "ROOT",
"DOCUMENT");
+
+ // Let''s break it down
+ XMLDOC.Parser.eat(doc, src);
+
+ return doc;
+};
+
+/**
+ * The XML fragment processing routine. This method is private and should
not be called
+ * directly.
+ * @param parentNode {XMLDOC.Parser.node} The node which is the parent of
this fragment
+ * @param src {String} The source within the fragment to process
+ * @private
+ */
+XMLDOC.Parser.eat = function(parentNode, src)
+{
+ // A simple tag def
+ var reTag = new
RegExp("<(!|)(\\?|--|)((.|\\s)*?)\\2>","g");
+
+ // Special tag types
+ var reCommentTag = /<!--((.|\s)*?)-->/;
+ var rePITag = /<\?((.|\s)*?)\?>/;
+
+ // A start tag (with potential empty marker)
+ var reStartTag = /<(.*?)(
+([\w_\-]*)=(\"|'')(.*)\4)*(\/)?>/;
+
+ // An empty HTML style tag (not proper XML, but we''ll accept it so
we
can process HTML)
+ var reHTMLEmptyTag = /<(.*?)(
+([\w_\-]*)=(\"|'')(.*)\4)*>/;
+
+ // Fully enclosing tag with nested tags
+ var reEnclosingTag = /<(.*?)(
+([\w_\-]*)=(\"|'')(.*?)\4)*>((.|
\s)*?)<\/\1>/;
+
+ // Breaks down attributes
+ var reAttributes = new RegExp("
+([\\w_\\-]*)=(\"|'')(.*?)\\2","g");
+
+ // Find us a tag
+ var tag;
+ while ((tag = reTag.exec(src)) != null)
+ {
+ if (tag.index > 0)
+ {
+ // The next tag has some text before it
+ var text = src.substring(0, tag.index).replace(/^[ \t\n]+((.|
\n)*?)[ \t\n]+$/, "$1");
+
+ if (text.length > 0 && (text != "\n"))
+ {
+ var txtnode = new XMLDOC.Parser.node(parentNode, "",
"TEXT");
+ txtnode.charData = text;
+
+ // Append the new text node
+ parentNode.nodes.push(txtnode);
+ }
+
+ // Reset the lastIndex of reTag
+ reTag.lastIndex -= src.substring(0, tag.index).length;
+
+ // Eat the text
+ src = src.substring(tag.index);
+ }
+
+ if (reCommentTag.test(tag[0]))
+ {
+ // Is this a comment?
+ var comment = new XMLDOC.Parser.node(parentNode, "",
"COMMENT");
+ comment.charData = reCommentTag.exec(tag[0])[1];
+
+ // Append the comment
+ parentNode.nodes.push(comment);
+
+ // Move the lastIndex of reTag
+ reTag.lastIndex -= tag[0].length;
+
+ // Eat the tag
+ src = src.replace(reCommentTag, "");
+ }
+ else if (rePITag.test(tag[0]))
+ {
+ // Is this a processing instruction?
+ var pi = new XMLDOC.Parser.node(parentNode, "",
"PI");
+ pi.charData = rePITag.exec(tag[0])[1];
+
+ // Append the processing instruction
+ parentNode.nodes.push(pi);
+
+ // Move the lastIndex of reTag
+ reTag.lastIndex -= tag[0].length;
+
+ // Eat the tag
+ src = src.replace(rePITag, "");
+ }
+ else if (reStartTag.test(tag[0]))
+ {
+ // Break it down
+ var e = reStartTag.exec(tag[0]);
+ var elem = new XMLDOC.Parser.node(parentNode, e[1],
"ELEMENT");
+
+ // Get attributes from the tag
+ var a;
+ while ((a = reAttributes.exec(e[2])) != null )
+ {
+ elem.attrs[a[1]] = a[3];
+ }
+
+ // Is this an empty XML-style tag?
+ if (e[6] == "/")
+ {
+ // Append the empty element
+ parentNode.nodes.push(elem);
+
+ // Move the lastIndex of reTag (include the start tag length)
+ reTag.lastIndex -= e[0].length;
+
+ // Eat the tag
+ src = src.replace(reStartTag, "");
+ }
+ else
+ {
+ // Check for malformed XML tags
+ var htmlParsed = false;
+ var htmlStartTag = reHTMLEmptyTag.exec(src);
+
+ // See if there isn''t an end tag within this block
+ var reHTMLEndTag = new RegExp("</" + htmlStartTag[1] +
">");
+ var htmlEndTag = reHTMLEndTag.exec(src);
+
+ if (XMLDOC.Parser.strictMode && htmlEndTag == null)
+ {
+ // Poorly formed XML fails in strict mode
+ var err = new Error("Malformed XML passed to
XMLDOC.Parser... Error contains malformed ''src''");
+ err.src = src;
+ throw err;
+ }
+ else if (htmlEndTag == null)
+ {
+ // This is an HTML-style empty tag, store the element for
it in non-strict mode
+ parentNode.nodes.push(elem);
+
+ // Eat the tag
+ src = src.replace(reHTMLEmptyTag, "");
+ htmlParsed = true;
+ }
+
+ // If we didn''t parse HTML-style, it must be an enclosing
tag
+ if (!htmlParsed)
+ {
+ var enc = reEnclosingTag.exec(src);
+
+ // Go deeper into the document
+ XMLDOC.Parser.eat(elem, enc[6]);
+
+ // Append the new element node
+ parentNode.nodes.push(elem);
+
+ // Eat the tag
+ src = src.replace(reEnclosingTag, "");
+ }
+ }
+
+ // Reset the lastIndex of reTag
+ reTag.lastIndex = 0;
+ }
+ }
+
+ // No tag was found... append the text if there is any
+ src = src.replace(/^[ \t\n]+((.|\n)*?)[ \t\n]+$/, "$1");
+ if (src.length > 0 && (src != "\n"))
+ {
+ var txtNode = new XMLDOC.Parser.node(parentNode, "",
"TEXT");
+ txtNode.charData = src;
+
+ // Append the new text node
+ parentNode.nodes.push(txtNode);
+ }
+};
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/handlers/XMLDOC.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,26 @@
+/**
+ * This is the main container for the XMLDOC handler.
+ * @namespace
+ * @author Brett Fattori (bfattori at fry.com)
+ * @version $Revision: 498 $
+ */
+XMLDOC = {
+
+};
+
+/** The current version string of this application. */
+XMLDOC.VERSION = "1.0";
+
+/** Include the library necessary to handle XML files */
+IO.includeDir("handlers/XMLDOC/");
+
+/**
+ * @type Symbol[]
+ */
+XMLDOC.handle = function(srcFile, src) {
+
+};
+
+XMLDOC.publish = function(symbolgroup) {
+
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/DocComment.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,200 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ Create a new DocComment. This takes a raw documentation comment,
+ and wraps it in useful accessors.
+ @class Represents a documentation comment object.
+ */
+JSDOC.DocComment = function(/**String*/comment) {
+ this.init();
+ if (typeof comment != "undefined") {
+ this.parse(comment);
+ }
+}
+
+JSDOC.DocComment.prototype.init = function() {
+ this.isUserComment = true;
+ this.src = "";
+ this.meta = "";
+ this.tagTexts = [];
+ this.tags = [];
+}
+
+/**
+ @requires JSDOC.DocTag
+ */
+JSDOC.DocComment.prototype.parse = function(/**String*/comment) {
+ if (comment == "") {
+ comment = "/** @desc */";
+ this.isUserComment = false;
+ }
+
+ this.src = JSDOC.DocComment.unwrapComment(comment);
+
+ this.meta = "";
+ if (this.src.indexOf("#") == 0) {
+ this.src.match(/#(.+[+-])([\s\S]*)$/);
+ if (RegExp.$1) this.meta = RegExp.$1;
+ if (RegExp.$2) this.src = RegExp.$2;
+ }
+
+ if (typeof JSDOC.PluginManager != "undefined") {
+ JSDOC.PluginManager.run("onDocCommentSrc", this);
+ }
+
+ this.fixDesc();
+
+ this.src = JSDOC.DocComment.shared+"\n"+this.src;
+
+ this.tagTexts + this.src
+ .split(/(^|[\r\n])\s*@/)
+ .filter(function($){return $.match(/\S/)});
+
+ /**
+ The tags found in the comment.
+ @type JSDOC.DocTag[]
+ */
+ this.tags = this.tagTexts.map(function($){return new JSDOC.DocTag($)});
+
+ if (typeof JSDOC.PluginManager != "undefined") {
+ JSDOC.PluginManager.run("onDocCommentTags", this);
+ }
+}
+
+/*t:
+ plan(5, "testing JSDOC.DocComment");
+ requires("../frame/String.js");
+ requires("../lib/JSDOC/DocTag.js");
+
+ var com = new JSDOC.DocComment("/**@foo some\n* comment
here*"+"/");
+ is(com.tagTexts[0], "foo some\ncomment here", "first tag text
is found.");
+ is(com.tags[0].title, "foo", "the title is found in a comment
with one
tag.");
+
+ var com = new JSDOC.DocComment("/** @foo first\n* @bar
second*"+"/");
+ is(com.getTag("bar").length, 1, "getTag() returns one tag by
that
title.");
+
+ JSDOC.DocComment.shared = "@author John Smith";
+ var com = new JSDOC.DocComment("/**@foo some\n* comment
here*"+"/");
+ is(com.tags[0].title, "author", "shared comment is
added.");
+ is(com.tags[1].title, "foo", "shared comment is added to
existing tag.");
+*/
+
+/**
+ If no @desc tag is provided, this function will add it.
+ */
+JSDOC.DocComment.prototype.fixDesc = function() {
+ if (this.meta && this.meta != "@+") return;
+ if (/^\s*[^@\s]/.test(this.src)) {
+ this.src = "@desc "+this.src;
+ }
+}
+
+/*t:
+ plan(5, "testing JSDOC.DocComment#fixDesc");
+
+ var com = new JSDOC.DocComment();
+
+ com.src = "this is a desc\n at author foo";
+ com.fixDesc();
+ is(com.src, "@desc this is a desc\n at author foo", "if no
@desc tag is
provided one is added.");
+
+ com.src = "x";
+ com.fixDesc();
+ is(com.src, "@desc x", "if no @desc tag is provided one is
added to a
single character.");
+
+ com.src = "\nx";
+ com.fixDesc();
+ is(com.src, "@desc \nx", "if no @desc tag is provided one is
added to
return and character.");
+
+ com.src = " ";
+ com.fixDesc();
+ is(com.src, " ", "if no @desc tag is provided one is not added
to just
whitespace.");
+
+ com.src = "";
+ com.fixDesc();
+ is(com.src, "", "if no @desc tag is provided one is not added
to empty.");
+*/
+
+/**
+ Remove slash-star comment wrapper from a raw comment string.
+ @type String
+ */
+JSDOC.DocComment.unwrapComment = function(/**String*/comment) {
+ if (!comment) return "";
+ var unwrapped = comment.replace(/(^\/\*\*|
\*\/$)/g, "").replace(/^\s*\* ?/gm, "");
+ return unwrapped;
+}
+
+/*t:
+ plan(5, "testing JSDOC.DocComment.unwrapComment");
+
+ var com = "/**x*"+"/";
+ var unwrapped = JSDOC.DocComment.unwrapComment(com);
+ is(unwrapped, "x", "a single character jsdoc is found.");
+
+ com = "/***x*"+"/";
+ unwrapped = JSDOC.DocComment.unwrapComment(com);
+ is(unwrapped, "x", "three stars are allowed in the
opener.");
+
+ com = "/****x*"+"/";
+ unwrapped = JSDOC.DocComment.unwrapComment(com);
+ is(unwrapped, "*x", "fourth star in the opener is kept.");
+
+ com = "/**x\n * y\n*"+"/";
+ unwrapped = JSDOC.DocComment.unwrapComment(com);
+ is(unwrapped, "x\ny\n", "leading stars and spaces are
trimmed.");
+
+ com = "/**x\n * y\n*"+"/";
+ unwrapped = JSDOC.DocComment.unwrapComment(com);
+ is(unwrapped, "x\n y\n", "only first space after leading stars
are
trimmed.");
+*/
+
+/**
+ Provides a printable version of the comment.
+ @type String
+ */
+JSDOC.DocComment.prototype.toString = function() {
+ return this.src;
+}
+
+/*t:
+ plan(1, "testing JSDOC.DocComment#fixDesc");
+ var com = new JSDOC.DocComment();
+ com.src = "foo";
+ is(""+com, "foo", "stringifying a comment returns the
unwrapped src.");
+*/
+
+/**
+ Given the title of a tag, returns all tags that have that title.
+ @type JSDOC.DocTag[]
+ */
+JSDOC.DocComment.prototype.getTag = function(/**String*/tagTitle) {
+ return this.tags.filter(function($){return $.title == tagTitle});
+}
+
+/*t:
+ plan(1, "testing JSDOC.DocComment#getTag");
+ requires("../frame/String.js");
+ requires("../lib/JSDOC/DocTag.js");
+
+ var com = new JSDOC.DocComment("/**@foo some\n* @bar\n*
@bar*"+"/");
+ is(com.getTag("bar").length, 2, "getTag returns expected number
of
tags.");
+*/
+
+/**
+ Used to store the currently shared tag text.
+*/
+JSDOC.DocComment.shared = "";
+
+/*t:
+ plan(2, "testing JSDOC.DocComment.shared");
+ requires("../frame/String.js");
+ requires("../lib/JSDOC/DocTag.js");
+
+ JSDOC.DocComment.shared = "@author Michael";
+
+ var com = new JSDOC.DocComment("/**@foo\n* @foo*"+"/");
+ is(com.getTag("author").length, 1, "getTag returns shared
tag.");
+ is(com.getTag("foo").length, 2, "getTag returns unshared tags
too.");
+*/
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/DocTag.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,294 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ @constructor
+ */
+JSDOC.DocTag = function(src) {
+ this.init();
+ if (typeof src != "undefined") {
+ this.parse(src);
+ }
+}
+
+/**
+ Create and initialize the properties of this.
+ */
+JSDOC.DocTag.prototype.init = function() {
+ this.title = "";
+ this.type = "";
+ this.name = "";
+ this.isOptional = false;
+ this.defaultValue = "";
+ this.desc = "";
+
+ return this;
+}
+
+/**
+ Populate the properties of this from the given tag src.
+ @param {string} src
+ */
+JSDOC.DocTag.prototype.parse = function(src) {
+ if (typeof src != "string") throw "src must be a string not
"+(typeof
src);
+
+ try {
+ src = this.nibbleTitle(src);
+ if (JSDOC.PluginManager) {
+ JSDOC.PluginManager.run("onDocTagSynonym", this);
+ }
+
+ src = this.nibbleType(src);
+
+ // only some tags are allowed to have names.
+ if (this.title == "param" || this.title == "property" ||
this.title
== "config") { // @config is deprecated
+ src = this.nibbleName(src);
+ }
+ }
+ catch(e) {
+ if (LOG) LOG.warn(e);
+ else throw e;
+ }
+ this.desc = src; // whatever is left
+
+ // example tags need to have whitespace preserved
+ if (this.title != "example") this.desc = this.desc.trim();
+
+ if (JSDOC.PluginManager) {
+ JSDOC.PluginManager.run("onDocTag", this);
+ }
+}
+
+/**
+ Automatically called when this is stringified.
+ */
+JSDOC.DocTag.prototype.toString = function() {
+ return this.desc;
+}
+
+/*t:
+ plan(1, "testing JSDOC.DocTag#toString");
+
+ var tag = new JSDOC.DocTag("param {object} date A valid date.");
+ is(""+tag, "A valid date.", "stringifying a tag
returns the desc.");
+ */
+
+/**
+ Find and shift off the title of a tag.
+ @param {string} src
+ @return src
+ */
+JSDOC.DocTag.prototype.nibbleTitle = function(src) {
+ if (typeof src != "string") throw "src must be a string not
"+(typeof
src);
+
+ var parts = src.match(/^\s*(\S+)(?:\s([\s\S]*))?$/);
+
+ if (parts && parts[1]) this.title = parts[1];
+ if (parts && parts[2]) src = parts[2];
+ else src = "";
+
+ return src;
+}
+
+/*t:
+ plan(8, "testing JSDOC.DocTag#nibbleTitle");
+
+ var tag = new JSDOC.DocTag();
+
+ tag.init().nibbleTitle("aTitleGoesHere");
+ is(tag.title, "aTitleGoesHere", "a title can be found in a
single-word
string.");
+
+ var src = tag.init().nibbleTitle("aTitleGoesHere and the rest");
+ is(tag.title, "aTitleGoesHere", "a title can be found in a
multi-word
string.");
+ is(src, "and the rest", "the rest is returned when the title is
nibbled
off.");
+
+ src = tag.init().nibbleTitle("");
+ is(tag.title, "", "given an empty string the title is
empty.");
+ is(src, "", "the rest is empty when the tag is empty.");
+
+ var src = tag.init().nibbleTitle(" aTitleGoesHere\n a
description");
+ is(tag.title, "aTitleGoesHere", "leading and trailing spaces
are not part
of the title.");
+ is(src, " a description", "leading spaces (less one) are part
of the
description.");
+
+ tag.init().nibbleTitle("a.Title::Goes_Here foo");
+ is(tag.title, "a.Title::Goes_Here", "titles with punctuation
are
allowed.");
+ */
+
+/**
+ Find and shift off the type of a tag.
+ @requires frame/String.js
+ @param {string} src
+ @return src
+ */
+JSDOC.DocTag.prototype.nibbleType = function(src) {
+ if (typeof src != "string") throw "src must be a string not
"+(typeof
src);
+
+ if (src.match(/^\s*\{/)) {
+ var typeRange = src.balance("{", "}");
+ if (typeRange[1] == -1) {
+ throw "Malformed comment tag ignored. Tag type requires an opening {
and a closing }: "+src;
+ }
+ this.type = src.substring(typeRange[0]+1, typeRange[1]).trim();
+ this.type = this.type.replace(/\s*,\s*/g, "|"); // multiples can be
separated by , or |
+ src = src.substring(typeRange[1]+1);
+ }
+
+ return src;
+}
+
+/*t:
+ plan(5, "testing JSDOC.DocTag.parser.nibbleType");
+ requires("../frame/String.js");
+
+ var tag = new JSDOC.DocTag();
+
+ tag.init().nibbleType("{String[]} aliases");
+ is(tag.type, "String[]", "type can have non-alpha
characters.");
+
+ tag.init().nibbleType("{ aTypeGoesHere } etc etc");
+ is(tag.type, "aTypeGoesHere", "type is trimmed.");
+
+ tag.init().nibbleType("{ oneType, twoType ,\n threeType } etc
etc");
+ is(tag.type, "oneType|twoType|threeType", "multiple types can
be
separated by commas.");
+
+ var error;
+ try { tag.init().nibbleType("{widget foo"); }
+ catch(e) { error = e; }
+ is(typeof error, "string", "malformed tag type throws
error.");
+ isnt(error.indexOf("Malformed"), -1, "error message tells tag
is
malformed.");
+ */
+
+/**
+ Find and shift off the name of a tag.
+ @requires frame/String.js
+ @param {string} src
+ @return src
+ */
+JSDOC.DocTag.prototype.nibbleName = function(src) {
+ if (typeof src != "string") throw "src must be a string not
"+(typeof
src);
+
+ src = src.trim();
+
+ // is optional?
+ if (src.charAt(0) == "[") {
+ var nameRange = src.balance("[", "]");
+ if (nameRange[1] == -1) {
+ throw "Malformed comment tag ignored. Tag optional name requires an
opening [ and a closing ]: "+src;
+ }
+ this.name = src.substring(nameRange[0]+1, nameRange[1]).trim();
+ this.isOptional = true;
+
+ src = src.substring(nameRange[1]+1);
+
+ // has default value?
+ var nameAndValue = this.name.split("=");
+ if (nameAndValue.length) {
+ this.name = nameAndValue.shift().trim();
+ this.defaultValue = nameAndValue.join("=");
+ }
+ }
+ else {
+ var parts = src.match(/^(\S+)(?:\s([\s\S]*))?$/);
+ if (parts) {
+ if (parts[1]) this.name = parts[1];
+ if (parts[2]) src = parts[2].trim();
+ else src = "";
+ }
+ }
+
+ return src;
+}
+
+/*t:
+ requires("../frame/String.js");
+ plan(9, "testing JSDOC.DocTag.parser.nibbleName");
+
+ var tag = new JSDOC.DocTag();
+
+ tag.init().nibbleName("[foo] This is a description.");
+ is(tag.isOptional, true, "isOptional syntax is detected.");
+ is(tag.name, "foo", "optional param name is found.");
+
+ tag.init().nibbleName("[foo] This is a description.");
+ is(tag.isOptional, true, "isOptional syntax is detected when no
type.");
+ is(tag.name, "foo", "optional param name is found when no
type.");
+
+ tag.init().nibbleName("[foo=7] This is a description.");
+ is(tag.name, "foo", "optional param name is found when default
value.");
+ is(tag.defaultValue, 7, "optional param default value is found when
default value.");
+
+ //tag.init().nibbleName("[foo= a value] This is a description.");
+ //is(tag.defaultValue, " a value", "optional param default
value is
found when default value has spaces (issue #112).");
+
+ tag.init().nibbleName("[foo=[]] This is a description.");
+ is(tag.defaultValue, "[]", "optional param default value is
found when
default value is [] (issue #95).");
+
+ tag.init().nibbleName("[foo=a=b] This is a description.");
+ is(tag.name, "foo", "optional param name is found when default
value is
a=b.");
+ is(tag.defaultValue, "a=b", "optional param default value is
found when
default value is a=b.")
+ */
+
+/*t:
+ plan(32, "Testing JSDOC.DocTag.parser.");
+ requires("../frame/String.js");
+
+ var tag = new JSDOC.DocTag();
+
+ is(typeof tag, "object", "JSDOC.DocTag.parser with an empty
string
returns an object.");
+ is(typeof tag.title, "string", "returned object has a string
property ''title''.");
+ is(typeof tag.type, "string", "returned object has a string
property ''type''.");
+ is(typeof tag.name, "string", "returned object has a string
property ''name''.");
+ is(typeof tag.defaultValue, "string", "returned object has a
string
property ''defaultValue''.");
+ is(typeof tag.isOptional, "boolean", "returned object has a
boolean
property ''isOptional''.");
+ is(typeof tag.desc, "string", "returned object has a string
property ''desc''.");
+
+ tag = new JSDOC.DocTag("param {widget} foo");
+ is(tag.title, "param", "param title is found.");
+ is(tag.name, "foo", "param name is found when desc is
missing.");
+ is(tag.desc, "", "param desc is empty when missing.");
+
+ tag = new JSDOC.DocTag("param {object} date A valid date.");
+ is(tag.name, "date", "param name is found with a type.");
+ is(tag.type, "object", "param type is found.");
+ is(tag.desc, "A valid date.", "param desc is found with a
type.");
+
+ tag = new JSDOC.DocTag("param aName a description goes\n
here.");
+ is(tag.name, "aName", "param name is found without a
type.");
+ is(tag.desc, "a description goes\n here.", "param desc is
found
without a type.");
+
+ tag = new JSDOC.DocTag("param {widget}");
+ is(tag.name, "", "param name is empty when it is not
given.");
+
+ tag = new JSDOC.DocTag("param {widget} [foo] This is a
description.");
+ is(tag.name, "foo", "optional param name is found.");
+
+ tag = new JSDOC.DocTag("return {aType} This is a description.");
+ is(tag.type, "aType", "when return tag has no name, type is
found.");
+ is(tag.desc, "This is a description.", "when return tag has no
name, desc
is found.");
+
+ tag = new JSDOC.DocTag("author Joe Coder <jcoder at
example.com>");
+ is(tag.title, "author", "author tag has a title.");
+ is(tag.type, "", "the author tag has no type.");
+ is(tag.name, "", "the author tag has no name.");
+ is(tag.desc, "Joe Coder <jcoder at example.com>", "author
tag has desc.");
+
+ tag = new JSDOC.DocTag("private \t\n ");
+ is(tag.title, "private", "private tag has a title.");
+ is(tag.type, "", "the private tag has no type.");
+ is(tag.name, "", "the private tag has no name.");
+ is(tag.desc, "", "private tag has no desc.");
+
+ tag = new JSDOC.DocTag("example\n example(code);\n more();");
+ is(tag.desc, " example(code);\n more();", "leading
whitespace (less
one) in examples code is preserved.");
+
+ tag = new JSDOC.DocTag("param theName \n");
+ is(tag.name, "theName", "name only is found.");
+
+ tag = new JSDOC.DocTag("type theDesc \n");
+ is(tag.desc, "theDesc", "desc only is found.");
+
+ tag = new JSDOC.DocTag("type {theType} \n");
+ is(tag.type, "theType", "type only is found.");
+
+ tag = new JSDOC.DocTag("");
+ is(tag.title, "", "title is empty when tag is empty.");
+ */
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/JsDoc.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,126 @@
+/**
+ @constructor
+ @param [opt] Used to override the commandline options. Useful for testing.
+ @version $Id: JsDoc.js 773 2009-01-24 09:42:04Z micmath $
+*/
+JSDOC.JsDoc = function(/**object*/ opt) {
+ if (opt) {
+ JSDOC.opt = opt;
+ }
+
+ if (JSDOC.opt.h) {
+ JSDOC.usage();
+ quit();
+ }
+
+ // defend against options that are not sane
+ if (JSDOC.opt._.length == 0) {
+ LOG.warn("No source files to work on. Nothing to do.");
+ quit();
+ }
+ if (JSDOC.opt.t === true || JSDOC.opt.d === true) {
+ JSDOC.usage();
+ }
+
+ if (typeof JSDOC.opt.d == "string") {
+ if (!JSDOC.opt.d.charAt(JSDOC.opt.d.length-1).match(/[\\\/]/)) {
+ JSDOC.opt.d = JSDOC.opt.d+"/";
+ }
+ LOG.inform("Output directory set to
''"+JSDOC.opt.d+"''.");
+ IO.mkPath(JSDOC.opt.d);
+ }
+ if (JSDOC.opt.e) IO.setEncoding(JSDOC.opt.e);
+
+ // the -r option: scan source directories recursively
+ if (typeof JSDOC.opt.r == "boolean") JSDOC.opt.r = 10;
+ else if (!isNaN(parseInt(JSDOC.opt.r))) JSDOC.opt.r =
parseInt(JSDOC.opt.r);
+ else JSDOC.opt.r = 1;
+
+ // the -D option: define user variables
+ var D = {};
+ if (JSDOC.opt.D) {
+ for (var i = 0; i < JSDOC.opt.D.length; i++) {
+ var defineParts = JSDOC.opt.D[i].split(":", 2);
+ if (defineParts) D[defineParts[0]] = defineParts[1];
+ }
+ }
+ JSDOC.opt.D = D;
+ // combine any conf file D options with the commandline D options
+ if (defined(JSDOC.conf)) for (var c in JSDOC.conf.D) {
+ if (!defined(JSDOC.opt.D[c])) {
+ JSDOC.opt.D[c] = JSDOC.conf.D[c];
+ }
+ }
+
+ // Give plugins a chance to initialize
+ if (defined(JSDOC.PluginManager)) {
+ JSDOC.PluginManager.run("onInit", JSDOC.opt);
+ }
+
+ JSDOC.opt.srcFiles = JSDOC.JsDoc._getSrcFiles();
+ JSDOC.JsDoc._parseSrcFiles();
+ JSDOC.JsDoc.symbolSet = JSDOC.Parser.symbols;
+}
+
+/**
+ Retrieve source file list.
+ @returns {String[]} The pathnames of the files to be parsed.
+ */
+JSDOC.JsDoc._getSrcFiles = function() {
+ JSDOC.JsDoc.srcFiles = [];
+
+ var ext = ["js"];
+ if (JSDOC.opt.x) {
+ ext = JSDOC.opt.x.split(",").map(function($) {return
$.toLowerCase()});
+ }
+
+ for (var i = 0; i < JSDOC.opt._.length; i++) {
+ JSDOC.JsDoc.srcFiles = JSDOC.JsDoc.srcFiles.concat(
+ IO.ls(JSDOC.opt._[i], JSDOC.opt.r).filter(
+ function($) {
+ var thisExt = $.split(".").pop().toLowerCase();
+
+ if (JSDOC.opt.E) {
+ for(var n = 0; n < JSDOC.opt.E.length; n++) {
+ if ($.match(new RegExp(JSDOC.opt.E[n]))) {
+ LOG.inform("Excluding " + $);
+ return false; // if the file matches the regex then it''s
excluded.
+ }
+ }
+ }
+
+ return (ext.indexOf(thisExt) > -1); // we''re only interested
in files
with certain extensions
+ }
+ )
+ );
+ }
+
+ return JSDOC.JsDoc.srcFiles;
+}
+
+JSDOC.JsDoc._parseSrcFiles = function() {
+ JSDOC.Parser.init();
+ for (var i = 0, l = JSDOC.JsDoc.srcFiles.length; i < l; i++) {
+ var srcFile = JSDOC.JsDoc.srcFiles[i];
+
+ if (JSDOC.opt.v) LOG.inform("Parsing file: " + srcFile);
+
+ try {
+ var src = IO.readFile(srcFile);
+ }
+ catch(e) {
+ LOG.warn("Can''t read source file
''"+srcFile+"'': "+e.message);
+ }
+
+ var tr = new JSDOC.TokenReader();
+ var ts = new JSDOC.TokenStream(tr.tokenize(new JSDOC.TextStream(src)));
+
+ JSDOC.Parser.parse(ts, srcFile);
+
+ }
+ JSDOC.Parser.finish();
+
+ if (JSDOC.PluginManager) {
+ JSDOC.PluginManager.run("onFinishedParsing", JSDOC.Parser.symbols);
+ }
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/JsPlate.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,109 @@
+/**
+ @constructor
+*/
+JSDOC.JsPlate = function(templateFile) {
+ if (templateFile) this.template = IO.readFile(templateFile);
+
+ this.templateFile = templateFile;
+ this.code = "";
+ this.parse();
+}
+
+JSDOC.JsPlate.prototype.parse = function() {
+ this.template = this.template.replace(/\{#[\s\S]+?#\}/gi, "");
+ this.code = "var output=``"+this.template;
+
+ this.code = this.code.replace(
+ /<for +each="(.+?)" +in="(.+?)" *>/gi,
+ function (match, eachName, inName) {
+ return "``;\rvar $"+eachName+"_keys =
keys("+inName+");\rfor(var
$"+eachName+"_i = 0; $"+eachName+"_i <
$"+eachName+"_keys.length;
$"+eachName+"_i++) {\rvar $"+eachName+"_last =
($"+eachName+"_i ==
$"+eachName+"_keys.length-1);\rvar $"+eachName+"_key =
$"+eachName+"_keys[$"+eachName+"_i];\rvar
"+eachName+"
= "+inName+"[$"+eachName+"_key];\routput+=``";
+ }
+ );
+ this.code = this.code.replace(/<if test="(.+?)">/g,
"``;\rif ($1) {
output+=``");
+ this.code = this.code.replace(/<elseif test="(.+?)"\s*\/>/g,
"``;}\relse
if ($1) { output+=``");
+ this.code = this.code.replace(/<else\s*\/>/g, "``;}\relse {
output+=``");
+ this.code = this.code.replace(/<\/(if|for)>/g,
"``;\r};\routput+=``");
+ this.code = this.code.replace(
+ /\{\+\s*([\s\S]+?)\s*\+\}/gi,
+ function (match, code) {
+ code = code.replace(/"/g, "``"); // prevent qoute-escaping of
inline
code
+ code = code.replace(/(\r?\n)/g, " ");
+ return "``+ ("+code+") +``";
+ }
+ );
+ this.code = this.code.replace(
+ /\{!\s*([\s\S]+?)\s*!\}/gi,
+ function (match, code) {
+ code = code.replace(/"/g, "``"); // prevent qoute-escaping of
inline
code
+ code = code.replace(/(\n)/g, " ");
+ return "``; "+code+";\routput+=``";
+ }
+ );
+ this.code = this.code+"``;";
+
+ this.code = this.code.replace(/(\r?\n)/g, "\\n");
+ this.code = this.code.replace(/"/g, "\\\"");
+ this.code = this.code.replace(/``/g, "\"");
+}
+
+JSDOC.JsPlate.prototype.toCode = function() {
+ return this.code;
+}
+
+JSDOC.JsPlate.keys = function(obj) {
+ var keys = [];
+ if (obj.constructor.toString().indexOf("Array") > -1) {
+ for (var i = 0; i < obj.length; i++) {
+ keys.push(i);
+ }
+ }
+ else {
+ for (var i in obj) {
+ keys.push(i);
+ }
+ }
+ return keys;
+};
+
+JSDOC.JsPlate.values = function(obj) {
+ var values = [];
+ if (obj.constructor.toString().indexOf("Array") > -1) {
+ for (var i = 0; i < obj.length; i++) {
+ values.push(obj[i]);
+ }
+ }
+ else {
+ for (var i in obj) {
+ values.push(obj[i]);
+ }
+ }
+ return values;
+};
+
+JSDOC.JsPlate.prototype.process = function(data, compact) {
+ var keys = JSDOC.JsPlate.keys;
+ var values = JSDOC.JsPlate.values;
+
+ try {
+ eval(this.code);
+ }
+ catch (e) {
+ print(">> There was an error evaluating the compiled code from
template: "+this.templateFile);
+ print(" The error was on
line "+e.lineNumber+" "+e.name+": "+e.message);
+ var lines = this.code.split("\r");
+ if (e.lineNumber-2 >= 0)
print("line "+(e.lineNumber-1)+": "+lines[e.lineNumber-2]);
+ print("line "+e.lineNumber+": "+lines[e.lineNumber-1]);
+ print("");
+ }
+
+ if (compact) { // patch by mcbain.asm
+ // Remove lines that contain only space-characters, usually left by
lines in the template
+ // which originally only contained JSPlate tags or code. This makes it
easier to write
+ // non-tricky templates which still put out nice code (not bloated with
extra lines).
+ // Lines purposely left blank (just a line ending) are left alone.
+ output = output.replace(/\s+?(\r?)\n/g, "$1\n");
+ }
+
+ /*debug*///print(this.code);
+ return output;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Lang.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,144 @@
+/**
+ @namespace
+*/
+JSDOC.Lang = {
+}
+
+JSDOC.Lang.isBuiltin = function(name) {
+ return (JSDOC.Lang.isBuiltin.coreObjects.indexOf(name) > -1);
+}
+JSDOC.Lang.isBuiltin.coreObjects =
[''_global_'', ''Array'',
''Boolean'', ''Date'',
''Error'', ''Function'',
''Math'', ''Number'',
''Object'', ''RegExp'',
''String''];
+
+JSDOC.Lang.whitespace = function(ch) {
+ return JSDOC.Lang.whitespace.names[ch];
+}
+JSDOC.Lang.whitespace.names = {
+ " ": "SPACE",
+ "\f": "FORMFEED",
+ "\t": "TAB",
+ "\u0009": "UNICODE_TAB",
+ "\u000A": "UNICODE_NBR",
+ "\u0008": "VERTICAL_TAB"
+};
+
+JSDOC.Lang.newline = function(ch) {
+ return JSDOC.Lang.newline.names[ch];
+}
+JSDOC.Lang.newline.names = {
+ "\n": "NEWLINE",
+ "\r": "RETURN",
+ "\u000A": "UNICODE_LF",
+ "\u000D": "UNICODE_CR",
+ "\u2029": "UNICODE_PS",
+ "\u2028": "UNICODE_LS"
+};
+
+JSDOC.Lang.keyword = function(word) {
+ return JSDOC.Lang.keyword.names["="+word];
+}
+JSDOC.Lang.keyword.names = {
+ "=break": "BREAK",
+ "=case": "CASE",
+ "=catch": "CATCH",
+ "=const": "VAR",
+ "=continue": "CONTINUE",
+ "=default": "DEFAULT",
+ "=delete": "DELETE",
+ "=do": "DO",
+ "=else": "ELSE",
+ "=false": "FALSE",
+ "=finally": "FINALLY",
+ "=for": "FOR",
+ "=function": "FUNCTION",
+ "=if": "IF",
+ "=in": "IN",
+ "=instanceof": "INSTANCEOF",
+ "=new": "NEW",
+ "=null": "NULL",
+ "=return": "RETURN",
+ "=switch": "SWITCH",
+ "=this": "THIS",
+ "=throw": "THROW",
+ "=true": "TRUE",
+ "=try": "TRY",
+ "=typeof": "TYPEOF",
+ "=void": "VOID",
+ "=while": "WHILE",
+ "=with": "WITH",
+ "=var": "VAR"
+};
+
+JSDOC.Lang.punc = function(ch) {
+ return JSDOC.Lang.punc.names[ch];
+}
+JSDOC.Lang.punc.names = {
+ ";": "SEMICOLON",
+ ",": "COMMA",
+ "?": "HOOK",
+ ":": "COLON",
+ "||": "OR",
+ "&&": "AND",
+ "|": "BITWISE_OR",
+ "^": "BITWISE_XOR",
+ "&": "BITWISE_AND",
+ "===": "STRICT_EQ",
+ "==": "EQ",
+ "=": "ASSIGN",
+ "!==": "STRICT_NE",
+ "!=": "NE",
+ "<<": "LSH",
+ "<=": "LE",
+ "<": "LT",
+ ">>>": "URSH",
+ ">>": "RSH",
+ ">=": "GE",
+ ">": "GT",
+ "++": "INCREMENT",
+ "--": "DECREMENT",
+ "+": "PLUS",
+ "-": "MINUS",
+ "*": "MUL",
+ "/": "DIV",
+ "%": "MOD",
+ "!": "NOT",
+ "~": "BITWISE_NOT",
+ ".": "DOT",
+ "[": "LEFT_BRACKET",
+ "]": "RIGHT_BRACKET",
+ "{": "LEFT_CURLY",
+ "}": "RIGHT_CURLY",
+ "(": "LEFT_PAREN",
+ ")": "RIGHT_PAREN"
+};
+
+JSDOC.Lang.matching = function(name) {
+ return JSDOC.Lang.matching.names[name];
+}
+JSDOC.Lang.matching.names = {
+ "LEFT_PAREN": "RIGHT_PAREN",
+ "RIGHT_PAREN": "LEFT_PAREN",
+ "LEFT_CURLY": "RIGHT_CURLY",
+ "RIGHT_CURLY": "LEFT_CURLY",
+ "LEFT_BRACE": "RIGHT_BRACE",
+ "RIGHT_BRACE": "LEFT_BRACE"
+}
+
+JSDOC.Lang.isNumber = function(str) {
+ return /^(\.[0-9]|[0-9]+\.|[0-9])[0-9]*([eE][+-][0-9]+)?$/i.test(str);
+}
+
+JSDOC.Lang.isHexDec = function(str) {
+ return /^0x[0-9A-F]+$/i.test(str);
+}
+
+JSDOC.Lang.isWordChar = function(str) {
+ return /^[a-zA-Z0-9$_.]+$/.test(str);
+}
+
+JSDOC.Lang.isSpace = function(str) {
+ return (typeof JSDOC.Lang.whitespace(str) != "undefined");
+}
+
+JSDOC.Lang.isNewline = function(str) {
+ return (typeof JSDOC.Lang.newline(str) != "undefined");
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Parser.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,145 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ @namespace
+ @requires JSDOC.Walker
+ @requires JSDOC.Symbol
+ @requires JSDOC.DocComment
+*/
+JSDOC.Parser = {
+ conf: {
+ ignoreCode: JSDOC.opt.n,
+ ignoreAnonymous: true, // factory: true
+ treatUnderscoredAsPrivate: true, // factory: true
+ explain: false // factory: false
+ },
+
+ addSymbol: function(symbol) {
+
+if (JSDOC.Parser.rename) {
+ for (var n in JSDOC.Parser.rename) {
+ if (symbol.alias.indexOf(n) == 0) {
+ if (symbol.name == symbol.alias) {
+ symbol.name = symbol.name.replace(n, JSDOC.Parser.rename[n]);
+ }
+ symbol.alias = symbol.alias.replace(n, JSDOC.Parser.rename[n]);
+ }
+ }
+}
+
+if (JSDOC.opt.S) {
+ if (typeof JSDOC.Parser.secureModules == "undefined")
JSDOC.Parser.secureModules = {};
+ if (/^exports\./.test(symbol.alias)) {
+ symbol.srcFile.match(/(^|[\\\/])([^\\\/]+)\.js/i);
+ var fileNS = RegExp.$2;
+ symbol.alias = symbol.alias.replace(/^exports\./, fileNS);
+ symbol.name = symbol.name.replace(/^exports\./, "");
+ symbol.memberOf = fileNS;
+
+ // need to create the namespace associated with this file first
+ if (!JSDOC.Parser.secureModules[fileNS]) {
+ JSDOC.Parser.secureModules[fileNS] = 1;
+ var nsSymbol = new JSDOC.Symbol(fileNS, [], "GLOBAL", new
JSDOC.DocComment(""));
+ nsSymbol.isNamespace = true;
+ nsSymbol.srcFile = "";
+ nsSymbol.isPrivate = false;
+ nsSymbol.srcFile = symbol.srcFile;
+ nsSymbol.desc = (JSDOC.Parser.symbols.getSymbol(symbol.srcFile) ||
{desc: ""}).desc;
+ JSDOC.Parser.addSymbol(nsSymbol);
+
+ }
+ }
+ else { // a method that is not exported?
+ if (!symbol.isNamespace) return;
+ }
+}
+ // if a symbol alias is documented more than once the last one with the
user docs wins
+ if (JSDOC.Parser.symbols.hasSymbol(symbol.alias)) {
+ var oldSymbol = JSDOC.Parser.symbols.getSymbol(symbol.alias);
+ if (oldSymbol.comment.isUserComment) {
+ if (symbol.comment.isUserComment) { // old and new are both documented
+ LOG.warn("The symbol ''"+symbol.alias+"''
is documented more than
once.");
+ }
+ else { // old is documented but new isn''t
+ return;
+ }
+ }
+ }
+
+ // we don''t document anonymous things
+ if (JSDOC.Parser.conf.ignoreAnonymous &&
symbol.name.match(/\$anonymous\b/)) return;
+
+ // uderscored things may be treated as if they were marked private, this
cascades
+ if (JSDOC.Parser.conf.treatUnderscoredAsPrivate &&
symbol.name.match(/[.#-]_[^.#-]+$/)) {
+ if (!symbol.comment.getTag("public").length > 0)
symbol.isPrivate =
true;
+ }
+
+ // -p flag is required to document private things
+ if (!JSDOC.opt.p && symbol.isPrivate) return; // issue #161 fixed by
mcbain.asm
+
+ // ignored things are not documented, this doesn''t cascade
+ if (symbol.isIgnored) return;
+ JSDOC.Parser.symbols.addSymbol(symbol);
+ },
+
+ addBuiltin: function(name) {
+ var builtin = new JSDOC.Symbol(name, [], "CONSTRUCTOR", new
JSDOC.DocComment(""));
+ builtin.isNamespace = true;
+ builtin.srcFile = "";
+ builtin.isPrivate = false;
+ JSDOC.Parser.addSymbol(builtin);
+ return builtin;
+ },
+
+ init: function() {
+ JSDOC.Parser.symbols = new JSDOC.SymbolSet();
+ JSDOC.Parser.walker = new JSDOC.Walker();
+ },
+
+ finish: function() {
+ JSDOC.Parser.symbols.relate();
+
+ // make a litle report about what was found
+ if (JSDOC.Parser.conf.explain) {
+ var symbols = JSDOC.Parser.symbols.toArray();
+ var srcFile = "";
+ for (var i = 0, l = symbols.length; i < l; i++) {
+ var symbol = symbols[i];
+ if (srcFile != symbol.srcFile) {
+ srcFile = symbol.srcFile;
+ print("\n"+srcFile+"\n-------------------");
+ }
+ print(i+":\n alias => "+symbol.alias + "\n name
=> "+symbol.name+ "\n isa => "+symbol.isa + "\n
memberOf => " +
symbol.memberOf + "\n isStatic => " + symbol.isStatic + ",
isInner => " +
symbol.isInner+ ", isPrivate => " + symbol.isPrivate);
+ }
+ print("-------------------\n");
+ }
+ }
+}
+
+JSDOC.Parser.parse = function(/**JSDOC.TokenStream*/ts,
/**String*/srcFile) {
+ JSDOC.Symbol.srcFile = (srcFile || "");
+ JSDOC.DocComment.shared = ""; // shared comments don''t
cross file
boundaries
+
+ if (!JSDOC.Parser.walker) JSDOC.Parser.init();
+ JSDOC.Parser.walker.walk(ts); // adds to our symbols
+
+ // filter symbols by option
+ for (var p = JSDOC.Parser.symbols._index.first(); p; p =
JSDOC.Parser.symbols._index.next()) {
+ var symbol = p.value;
+
+ if (!symbol) continue;
+
+ if (symbol.is("FILE") || symbol.is("GLOBAL")) {
+ continue;
+ }
+ else if (!JSDOC.opt.a && !symbol.comment.isUserComment) {
+ JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
+ }
+
+ if (/#$/.test(symbol.alias)) { // we don''t document prototypes
+ JSDOC.Parser.symbols.deleteSymbol(symbol.alias);
+ }
+ }
+
+ return JSDOC.Parser.symbols.toArray();
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/PluginManager.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,33 @@
+/**
+ @namespace Holds functionality related to running plugins.
+*/
+JSDOC.PluginManager = {
+}
+
+/**
+ @param name A unique name that identifies that plugin.
+ @param handlers A collection of named functions. The names correspond to
hooks in the core code.
+*/
+JSDOC.PluginManager.registerPlugin = function(/**String*/name,
/**Object*/handlers) {
+ if (!defined(JSDOC.PluginManager.plugins))
+ /** The collection of all plugins. Requires a unique name for each.
+ */
+ JSDOC.PluginManager.plugins = {};
+
+
+ JSDOC.PluginManager.plugins[name] = handlers;
+}
+
+/**
+ @param hook The name of the hook that is being caught.
+ @param target Any object. This will be passed as the only argument to the
handler whose
+ name matches the hook name. Handlers cannot return a value, so must
modify the target
+ object to have an effect.
+*/
+JSDOC.PluginManager.run = function(/**String*/hook, /**Mixed*/target) {
+ for (var name in JSDOC.PluginManager.plugins) {
+ if (defined(JSDOC.PluginManager.plugins[name][hook])) {
+ JSDOC.PluginManager.plugins[name][hook](target);
+ }
+ }
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Symbol.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,642 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ Create a new Symbol.
+ @class Represents a symbol in the source code.
+ */
+JSDOC.Symbol = function() {
+ this.init();
+ if (arguments.length) this.populate.apply(this, arguments);
+}
+
+JSDOC.Symbol.prototype.init = function() {
+ this._name = "";
+ this._params = [];
+ this.$args = [];
+ this.addOn = "";
+ this.alias = "";
+ this.augments = [];
+ this.author = "";
+ this.classDesc = "";
+ this.comment = {};
+ this.defaultValue = undefined;
+ this.deprecated = "";
+ this.desc = "";
+ this.example = [];
+ this.exceptions = [];
+ this.fires = [];
+ this.inherits = [];
+ this.inheritsFrom = [];
+ this.isa = "OBJECT";
+ this.isConstant = false;
+ this.isEvent = false;
+ this.isIgnored = false;
+ this.isInner = false;
+ this.isNamespace = false;
+ this.isPrivate = false;
+ this.isStatic = false;
+ this.memberOf = "";
+ this.methods = [];
+ this.properties = [];
+ this.requires = [];
+ this.returns = [];
+ this.see = [];
+ this.since = "";
+ this.srcFile = {};
+ this.type = "";
+ this.version = "";
+}
+
+JSDOC.Symbol.prototype.serialize = function() {
+ var keys = [];
+ for (var p in this) {
+ keys.push (p);
+ }
+ keys = keys.sort();
+
+ var out = "";
+ for (var i in keys) {
+ if (typeof this[keys[i]] == "function") continue;
+ out += keys[i]+" =>
"+Dumper.dump(this[keys[i]])+",\n";
+ }
+ return "\n{\n" + out + "}\n";
+}
+
+JSDOC.Symbol.prototype.clone = function() {
+ var clone = new JSDOC.Symbol();
+ clone.populate.apply(clone, this.$args); // repopulate using the original
arguments
+ clone.srcFile = this.srcFile; // not the current srcFile, the one when
the original was made
+ return clone;
+}
+
+JSDOC.Symbol.prototype.__defineSetter__("name",
+ function(n) { n = n.replace(/^_global_[.#-]/, ""); n =
n.replace(/\.prototype\.?/g, ''#''); this._name = n; }
+);
+JSDOC.Symbol.prototype.__defineGetter__("name",
+ function() { return this._name; }
+);
+JSDOC.Symbol.prototype.__defineSetter__("params",
+ function(v) {
+ for (var i = 0, l = v.length; i < l; i++) {
+ if (v[i].constructor != JSDOC.DocTag) { // may be a generic object
parsed from signature, like {type:..., name:...}
+ this._params[i] = new JSDOC.DocTag("param"+((v[i].type)?"
{"+v[i].type+"}":"")+" "+v[i].name);
+ }
+ else {
+ this._params[i] = v[i];
+ }
+ }
+ }
+);
+JSDOC.Symbol.prototype.__defineGetter__("params",
+ function() { return this._params; }
+);
+
+JSDOC.Symbol.prototype.getEvents = function() {
+ var events = [];
+ for (var i = 0, l = this.methods.length; i < l; i++) {
+ if (this.methods[i].isEvent) {
+ this.methods[i].name = this.methods[i].name.replace("event:",
"");
+ events.push(this.methods[i]);
+ }
+ }
+ return events;
+}
+
+JSDOC.Symbol.prototype.getMethods = function() {
+ var nonEvents = [];
+ for (var i = 0, l = this.methods.length; i < l; i++) {
+ if (!this.methods[i].isEvent) {
+ nonEvents.push(this.methods[i]);
+ }
+ }
+ return nonEvents;
+}
+
+
+JSDOC.Symbol.prototype.populate = function(
+ /** String */ name,
+ /** Object[] */ params,
+ /** String */ isa,
+ /** JSDOC.DocComment */ comment
+) {
+ this.$args = arguments;
+
+ this.name = name;
+ this.alias = this.name;
+
+ this.params = params;
+ this.isa = (isa == "VIRTUAL")? "OBJECT":isa;
+ this.comment = comment || new JSDOC.DocComment("");
+ this.srcFile = JSDOC.Symbol.srcFile;
+
+ if (this.is("FILE") && !this.alias) this.alias =
this.srcFile;
+
+ this.setTags();
+
+ if (typeof JSDOC.PluginManager != "undefined") {
+ JSDOC.PluginManager.run("onSymbol", this);
+ }
+}
+
+JSDOC.Symbol.prototype.setTags = function() {
+ // @author
+ var authors = this.comment.getTag("author");
+ if (authors.length) {
+ this.author = authors.map(function($){return $.desc;}).join(", ");
+ }
+
+ /*t:
+ plan(34, "testing JSDOC.Symbol");
+
+ requires("../lib/JSDOC/DocComment.js");
+ requires("../frame/String.js");
+ requires("../lib/JSDOC/DocTag.js");
+
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@author Joe Smith*"+"/"));
+ is(sym.author, "Joe Smith", "@author tag, author is
found.");
+ */
+
+ // @desc
+ var descs = this.comment.getTag("desc");
+ if (descs.length) {
+ this.desc = descs.map(function($){return $.desc;}).join("\n"); //
multiple descriptions are concatenated into one
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@desc This is a description.*"+"/"));
+ is(sym.desc, "This is a description.", "@desc tag, description
is
found.");
+ */
+
+ // @overview
+ if (this.is("FILE")) {
+ if (!this.alias) this.alias = this.srcFile;
+
+ var overviews = this.comment.getTag("overview");
+ if (overviews.length) {
+ this.desc = [this.desc].concat(overviews.map(function($){return
$.desc;})).join("\n");
+ }
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@overview This is an overview.*"+"/"));
+ is(sym.desc, "\nThis is an overview.", "@overview tag,
description is
found.");
+ */
+
+ // @since
+ var sinces = this.comment.getTag("since");
+ if (sinces.length) {
+ this.since = sinces.map(function($){return $.desc;}).join(", ");
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@since 1.01*"+"/"));
+ is(sym.since, "1.01", "@since tag, description is
found.");
+ */
+
+ // @constant
+ if (this.comment.getTag("constant").length) {
+ this.isConstant = true;
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@constant*"+"/"));
+ is(sym.isConstant, true, "@constant tag, isConstant set.");
+ */
+
+ // @version
+ var versions = this.comment.getTag("version");
+ if (versions.length) {
+ this.version = versions.map(function($){return $.desc;}).join(",
");
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@version 2.0x*"+"/"));
+ is(sym.version, "2.0x", "@version tag, version is
found.");
+ */
+
+ // @deprecated
+ var deprecateds = this.comment.getTag("deprecated");
+ if (deprecateds.length) {
+ this.deprecated = deprecateds.map(function($){return
$.desc;}).join("\n");
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@deprecated Use other method.*"+"/"));
+ is(sym.deprecated, "Use other method.", "@deprecated tag, desc
is
found.");
+ */
+
+ // @example
+ var examples = this.comment.getTag("example");
+ if (examples.length) {
+ this.example = examples.map(
+ // trim trailing whitespace
+ function($) {
+ $.desc = $.desc.replace(/\s+$/, "");
+ return $;
+ }
+ );
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@example This\n is an example.
\n*"+"/"));
+ isnt(typeof sym.example[0], "undefined", "@example tag,
creates
sym.example array.");
+ is(sym.example[0], "This\n is an example.", "@example tag,
desc is
found.");
+ */
+
+ // @see
+ var sees = this.comment.getTag("see");
+ if (sees.length) {
+ var thisSee = this.see;
+ sees.map(function($){thisSee.push($.desc);});
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FILE", new
JSDOC.DocComment("/**@see The other thing.*"+"/"));
+ is(sym.see, "The other thing.", "@see tag, desc is
found.");
+ */
+
+ // @class
+ var classes = this.comment.getTag("class");
+ if (classes.length) {
+ this.isa = "CONSTRUCTOR";
+ this.classDesc = classes[0].desc; // desc can''t apply to the
constructor
as there is none.
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@class This describes the
class.*"+"/"));
+ is(sym.isa, "CONSTRUCTOR", "@class tag, makes symbol a
constructor.");
+ is(sym.classDesc, "This describes the class.", "@class tag,
class
description is found.");
+ */
+
+ // @namespace
+ var namespaces = this.comment.getTag("namespace");
+ if (namespaces.length) {
+ this.classDesc = namespaces[0].desc;
+ this.isNamespace = true;
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@namespace This describes the
namespace.*"+"/"));
+ is(sym.classDesc, "This describes the namespace.", "@namespace
tag,
class description is found.");
+ */
+
+ // @param
+ var params = this.comment.getTag("param");
+ if (params.length) {
+ // user-defined params overwrite those with same name defined by the
parser
+ var thisParams = this.params;
+
+ if (thisParams.length == 0) { // none exist yet, so just bung all these
user-defined params straight in
+ this.params = params;
+ }
+ else { // need to overlay these user-defined params on to existing
parser-defined params
+ for (var i = 0, l = params.length; i < l; i++) {
+ if (thisParams[i]) {
+ if (params[i].type) thisParams[i].type = params[i].type;
+ thisParams[i].name = params[i].name;
+ thisParams[i].desc = params[i].desc;
+ thisParams[i].isOptional = params[i].isOptional;
+ thisParams[i].defaultValue = params[i].defaultValue;
+ }
+ else thisParams[i] = params[i];
+ }
+ }
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [{type: "array",
name: "pages"}], "FUNCTION", new
JSDOC.DocComment("/**Description.*"+"/"));
+ is(sym.params.length, 1, "parser defined param is found.");
+
+ sym = new JSDOC.Symbol("foo", [], "FUNCTION", new
JSDOC.DocComment("/**Description.\n at param {array}
pages*"+"/"));
+ is(sym.params.length, 1, "user defined param is found.");
+ is(sym.params[0].type, "array", "user defined param type is
found.");
+ is(sym.params[0].name, "pages", "user defined param name is
found.");
+
+ sym = new JSDOC.Symbol("foo", [{type: "array",
name: "pages"}], "FUNCTION", new
JSDOC.DocComment("/**Description.\n at param
{string} uid*"+"/"));
+ is(sym.params.length, 1, "user defined param overwrites parser defined
param.");
+ is(sym.params[0].type, "string", "user defined param type
overwrites
parser defined param type.");
+ is(sym.params[0].name, "uid", "user defined param name
overwrites parser
defined param name.");
+
+ sym = new JSDOC.Symbol("foo", [{type: "array", name:
"pages"},
{type: "number", name: "count"}], "FUNCTION", new
JSDOC.DocComment("/**Description.\n at param {string}
uid*"+"/"));
+ is(sym.params.length, 2, "user defined params overlay parser defined
params.");
+ is(sym.params[1].type, "number", "user defined param type
overlays
parser defined param type.");
+ is(sym.params[1].name, "count", "user defined param name
overlays parser
defined param name.");
+
+ sym = new JSDOC.Symbol("foo", [], "FUNCTION", new
JSDOC.DocComment("/**Description.\n at param {array} pages The pages
description.*"+"/"));
+ is(sym.params.length, 1, "user defined param with description is
found.");
+ is(sym.params[0].desc, "The pages description.", "user defined
param
description is found.");
+ */
+
+ // @constructor
+ if (this.comment.getTag("constructor").length) {
+ this.isa = "CONSTRUCTOR";
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@constructor*"+"/"));
+ is(sym.isa, "CONSTRUCTOR", "@constructor tag, makes symbol a
constructor.");
+ */
+
+ // @static
+ if (this.comment.getTag("static").length) {
+ this.isStatic = true;
+ if (this.isa == "CONSTRUCTOR") {
+ this.isNamespace = true;
+ }
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@static\n at constructor*"+"/"));
+ is(sym.isStatic, true, "@static tag, makes isStatic true.");
+ is(sym.isNamespace, true, "@static and @constructor tag, makes
isNamespace true.");
+ */
+
+ // @inner
+ if (this.comment.getTag("inner").length) {
+ this.isInner = true;
+ this.isStatic = false;
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@inner*"+"/"));
+ is(sym.isStatic, false, "@inner tag, makes isStatic false.");
+ is(sym.isInner, true, "@inner makes isInner true.");
+ */
+
+ // @name
+ var names = this.comment.getTag("name");
+ if (names.length) {
+ this.name = names[0].desc;
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @field
+ if (this.comment.getTag("field").length) {
+ this.isa = "OBJECT";
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "FUNCTION", new
JSDOC.DocComment("/**@field*"+"/"));
+ is(sym.isa, "OBJECT", "@field tag, makes symbol an
object.");
+ */
+
+ // @function
+ if (this.comment.getTag("function").length) {
+ this.isa = "FUNCTION";
+ if (/event:/.test(this.alias)) this.isEvent = true;
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@function*"+"/"));
+ is(sym.isa, "FUNCTION", "@function tag, makes symbol a
function.");
+ */
+
+ // @event
+ var events = this.comment.getTag("event");
+ if (events.length) {
+ this.isa = "FUNCTION";
+ this.isEvent = true;
+ if (!/event:/.test(this.alias))
+ this.alias = this.alias.replace(/^(.*[.#-])([^.#-]+)$/,
"$1event:$2");
+ }
+
+ /*t:
+ var sym = new JSDOC.Symbol("foo", [], "OBJECT", new
JSDOC.DocComment("/**@event*"+"/"));
+ is(sym.isa, "FUNCTION", "@event tag, makes symbol a
function.");
+ is(sym.isEvent, true, "@event makes isEvent true.");
+ */
+
+ // @fires
+ var fires = this.comment.getTag("fires");
+ if (fires.length) {
+ for (var i = 0; i < fires.length; i++) {
+ this.fires.push(fires[i].desc);
+ }
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @property
+ var properties = this.comment.getTag("property");
+ if (properties.length) {
+ thisProperties = this.properties;
+ for (var i = 0; i < properties.length; i++) {
+ var property = new JSDOC.Symbol(this.alias+"#"+properties[i].name,
[], "OBJECT", new
JSDOC.DocComment("/**"+properties[i].desc+"\n at name
"+properties[i].name+"\n at memberOf
"+this.alias+"#*/"));
+ // TODO: shouldn''t the following happen in the addProperty method
of
Symbol?
+ property.name = properties[i].name;
+ property.memberOf = this.alias;
+ if (properties[i].type) property.type = properties[i].type;
+ if (properties[i].defaultValue) property.defaultValue =
properties[i].defaultValue;
+ this.addProperty(property);
+ JSDOC.Parser.addSymbol(property);
+ }
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @return
+ var returns = this.comment.getTag("return");
+ if (returns.length) { // there can be many return tags in a single doclet
+ this.returns = returns;
+ this.type = returns.map(function($){return $.type}).join(", ");
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @exception
+ this.exceptions = this.comment.getTag("throws");
+
+ /*t:
+ // todo
+ */
+
+ // @requires
+ var requires = this.comment.getTag("requires");
+ if (requires.length) {
+ this.requires = requires.map(function($){return $.desc});
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @type
+ var types = this.comment.getTag("type");
+ if (types.length) {
+ this.type = types[0].desc; //multiple type tags are ignored
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @private
+ if (this.comment.getTag("private").length || this.isInner) {
+ this.isPrivate = true;
+ }
+
+ // @ignore
+ if (this.comment.getTag("ignore").length) {
+ this.isIgnored = true;
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @inherits ... as ...
+ var inherits = this.comment.getTag("inherits");
+ if (inherits.length) {
+ for (var i = 0; i < inherits.length; i++) {
+ if
(/^\s*([a-z$0-9_.#:-]+)(?:\s+as\s+([a-z$0-9_.#:-]+))?/i.test(inherits[i].desc))
{
+ var inAlias = RegExp.$1;
+ var inAs = RegExp.$2 || inAlias;
+
+ if (inAlias) inAlias = inAlias.replace(/\.prototype\.?/g, "#");
+
+ if (inAs) {
+ inAs = inAs.replace(/\.prototype\.?/g, "#");
+ inAs = inAs.replace(/^this\.?/, "#");
+ }
+
+ if (inAs.indexOf(inAlias) != 0) { //not a full namepath
+ var joiner = ".";
+ if (this.alias.charAt(this.alias.length-1) == "#" ||
inAs.charAt(0)
== "#") {
+ joiner = "";
+ }
+ inAs = this.alias + joiner + inAs;
+ }
+ }
+ this.inherits.push({alias: inAlias, as: inAs});
+ }
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @augments
+ this.augments = this.comment.getTag("augments");
+
+ // @default
+ var defaults = this.comment.getTag("default");
+ if (defaults.length) {
+ if (this.is("OBJECT")) {
+ this.defaultValue = defaults[0].desc;
+ }
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @memberOf
+ var memberOfs = this.comment.getTag("memberOf");
+ if (memberOfs.length) {
+ this.memberOf = memberOfs[0].desc;
+ this.memberOf = this.memberOf.replace(/\.prototype\.?/g, "#");
+ }
+
+ /*t:
+ // todo
+ */
+
+ // @public
+ if (this.comment.getTag("public").length) {
+ this.isPrivate = false;
+ }
+
+ /*t:
+ // todo
+ */
+
+ if (JSDOC.PluginManager) {
+ JSDOC.PluginManager.run("onSetTags", this);
+ }
+}
+
+JSDOC.Symbol.prototype.is = function(what) {
+ return this.isa === what;
+}
+
+JSDOC.Symbol.prototype.isBuiltin = function() {
+ return JSDOC.Lang.isBuiltin(this.alias);
+}
+
+JSDOC.Symbol.prototype.setType = function(/**String*/comment,
/**Boolean*/overwrite) {
+ if (!overwrite && this.type) return;
+ var typeComment = JSDOC.DocComment.unwrapComment(comment);
+ this.type = typeComment;
+}
+
+JSDOC.Symbol.prototype.inherit = function(symbol) {
+ if (!this.hasMember(symbol.name) && !symbol.isInner) {
+ if (symbol.is("FUNCTION"))
+ this.methods.push(symbol);
+ else if (symbol.is("OBJECT"))
+ this.properties.push(symbol);
+ }
+}
+
+JSDOC.Symbol.prototype.hasMember = function(name) {
+ return (this.hasMethod(name) || this.hasProperty(name));
+}
+
+JSDOC.Symbol.prototype.addMember = function(symbol) {
+ if (symbol.is("FUNCTION")) { this.addMethod(symbol); }
+ else if (symbol.is("OBJECT")) { this.addProperty(symbol); }
+}
+
+JSDOC.Symbol.prototype.hasMethod = function(name) {
+ var thisMethods = this.methods;
+ for (var i = 0, l = thisMethods.length; i < l; i++) {
+ if (thisMethods[i].name == name) return true;
+ if (thisMethods[i].alias == name) return true;
+ }
+ return false;
+}
+
+JSDOC.Symbol.prototype.addMethod = function(symbol) {
+ var methodAlias = symbol.alias;
+ var thisMethods = this.methods;
+ for (var i = 0, l = thisMethods.length; i < l; i++) {
+ if (thisMethods[i].alias == methodAlias) {
+ thisMethods[i] = symbol; // overwriting previous method
+ return;
+ }
+ }
+ thisMethods.push(symbol); // new method with this alias
+}
+
+JSDOC.Symbol.prototype.hasProperty = function(name) {
+ var thisProperties = this.properties;
+ for (var i = 0, l = thisProperties.length; i < l; i++) {
+ if (thisProperties[i].name == name) return true;
+ if (thisProperties[i].alias == name) return true;
+ }
+ return false;
+}
+
+JSDOC.Symbol.prototype.addProperty = function(symbol) {
+ var propertyAlias = symbol.alias;
+ var thisProperties = this.properties;
+ for (var i = 0, l = thisProperties.length; i < l; i++) {
+ if (thisProperties[i].alias == propertyAlias) {
+ thisProperties[i] = symbol; // overwriting previous property
+ return;
+ }
+ }
+
+ thisProperties.push(symbol); // new property with this alias
+}
+
+JSDOC.Symbol.srcFile = ""; //running reference to the current file
being
parsed
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/SymbolSet.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,241 @@
+/** @constructor */
+JSDOC.SymbolSet = function() {
+ this.init();
+}
+
+JSDOC.SymbolSet.prototype.init = function() {
+ this._index = new Hash();
+}
+
+JSDOC.SymbolSet.prototype.keys = function() {
+ return this._index.keys();
+}
+
+JSDOC.SymbolSet.prototype.hasSymbol = function(alias) {
+ return this._index.hasKey(alias);
+}
+
+JSDOC.SymbolSet.prototype.addSymbol = function(symbol) {
+ if (this.hasSymbol(symbol.alias)) {
+ LOG.warn("Overwriting symbol documentation for: "+symbol.alias +
".");
+ }
+ this._index.set(symbol.alias, symbol);
+}
+
+JSDOC.SymbolSet.prototype.getSymbol = function(alias) {
+ if (this.hasSymbol(alias)) return this._index.get(alias);
+}
+
+JSDOC.SymbolSet.prototype.getSymbolByName = function(name) {
+ for (var p = this._index.first(); p; p = this._index.next()) {
+ var symbol = p.value;
+ if (symbol.name == name) return symbol;
+ }
+}
+
+JSDOC.SymbolSet.prototype.toArray = function() {
+ return this._index.values();
+}
+
+JSDOC.SymbolSet.prototype.deleteSymbol = function(alias) {
+ if (!this.hasSymbol(alias)) return;
+ this._index.drop(alias);
+}
+
+JSDOC.SymbolSet.prototype.renameSymbol = function(oldName, newName) {
+ // todo: should check if oldname or newname already exist
+ this._index.replace(oldName, newName);
+ this._index.get(newName).alias = newName;
+ return newName;
+}
+
+JSDOC.SymbolSet.prototype.relate = function() {
+ this.resolveBorrows();
+ this.resolveMemberOf();
+ this.resolveAugments();
+}
+
+JSDOC.SymbolSet.prototype.resolveBorrows = function() {
+ for (var p = this._index.first(); p; p = this._index.next()) {
+ var symbol = p.value;
+ if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
+
+ var borrows = symbol.inherits;
+ for (var i = 0; i < borrows.length; i++) {
+
+if (/#$/.test(borrows[i].alias)) {
+ LOG.warn("Attempted to borrow entire instance of
"+borrows[i].alias+" but
that feature is not yet implemented.");
+ return;
+}
+ var borrowed = this.getSymbol(borrows[i].alias);
+
+ if (!borrowed) {
+ LOG.warn("Can''t borrow undocumented
"+borrows[i].alias+".");
+ continue;
+ }
+
+ if (borrows[i].as == borrowed.alias) {
+ var assumedName = borrowed.name.split(/([#.-])/).pop();
+ borrows[i].as = symbol.name+RegExp.$1+assumedName;
+ LOG.inform("Assuming borrowed as name is "+borrows[i].as+"
but that
feature is experimental.");
+ }
+
+ var borrowAsName = borrows[i].as;
+ var borrowAsAlias = borrowAsName;
+ if (!borrowAsName) {
+ LOG.warn("Malformed @borrow, ''as'' is
required.");
+ continue;
+ }
+
+ if (borrowAsName.length > symbol.alias.length &&
borrowAsName.indexOf(symbol.alias) == 0) {
+ borrowAsName = borrowAsName.replace(borrowed.alias, "")
+ }
+ else {
+ var joiner = "";
+ if (borrowAsName.charAt(0) != "#") joiner = ".";
+ borrowAsAlias = borrowed.alias + joiner + borrowAsName;
+ }
+
+ borrowAsName = borrowAsName.replace(/^[#.]/, "");
+
+ if (this.hasSymbol(borrowAsAlias)) continue;
+
+ var clone = borrowed.clone();
+ clone.name = borrowAsName;
+ clone.alias = borrowAsAlias;
+ this.addSymbol(clone);
+ }
+ }
+}
+
+JSDOC.SymbolSet.prototype.resolveMemberOf = function() {
+ for (var p = this._index.first(); p; p = this._index.next()) {
+ var symbol = p.value;
+ if (symbol.is("FILE") || symbol.is("GLOBAL")) continue;
+
+ // the memberOf value was provided in the @memberOf tag
+ else if (symbol.memberOf) {
+
+ // like foo.bar is a memberOf foo
+ if (symbol.alias.indexOf(symbol.memberOf) == 0) {
+ var memberMatch = new
RegExp("^("+symbol.memberOf+")[.#-]?(.+)$");
+ var aliasParts = symbol.alias.match(memberMatch);
+
+ if (aliasParts) {
+ symbol.memberOf = aliasParts[1];
+ symbol.name = aliasParts[2];
+ }
+
+ var nameParts = symbol.name.match(memberMatch);
+
+ if (nameParts) {
+ symbol.name = nameParts[2];
+ }
+ }
+ // like bar is a memberOf foo
+ else {
+ var joiner = symbol.memberOf.charAt(symbol.memberOf.length-1);
+ if (!/[.#-]/.test(joiner)) symbol.memberOf += ".";
+ this.renameSymbol(symbol.alias, symbol.memberOf + symbol.name);
+ }
+ }
+ // the memberOf must be calculated
+ else {
+ var parts = symbol.alias.match(/^(.*[.#-])([^.#-]+)$/);
+ if (parts) {
+ symbol.memberOf = parts[1];
+ symbol.name = parts[2];
+ }
+ }
+
+ // set isStatic, isInner
+ if (symbol.memberOf) {
+ switch (symbol.memberOf.charAt(symbol.memberOf.length-1)) {
+ case ''#'' :
+ symbol.isStatic = false;
+ symbol.isInner = false;
+ break;
+ case ''.'' :
+ symbol.isStatic = true;
+ symbol.isInner = false;
+ break;
+ case ''-'' :
+ symbol.isStatic = false;
+ symbol.isInner = true;
+ break;
+ default: // memberOf ends in none of the above
+ symbol.isStatic = true;
+ break;
+ }
+ }
+
+ // unowned methods and fields belong to the global object
+ if (!symbol.is("CONSTRUCTOR") && !symbol.isNamespace
&& symbol.memberOf
== "") {
+ symbol.memberOf = "_global_";
+ }
+
+ // clean up
+ if (symbol.memberOf.match(/[.#-]$/)) {
+ symbol.memberOf = symbol.memberOf.substr(0, symbol.memberOf.length-1);
+ }
+ // add to parent''s methods or properties list
+ if (symbol.memberOf) {
+
+ var container = this.getSymbol(symbol.memberOf);
+ if (!container) {
+ if (JSDOC.Lang.isBuiltin(symbol.memberOf)) container =
JSDOC.Parser.addBuiltin(symbol.memberOf);
+ else {
+ LOG.warn("Trying to document "+symbol.name +" as a member
of
undocumented symbol "+symbol.memberOf+".");
+ }
+ }
+
+ if (container) container.addMember(symbol);
+ }
+ }
+}
+
+JSDOC.SymbolSet.prototype.resolveAugments = function() {
+ for (var p = this._index.first(); p; p = this._index.next()) {
+ var symbol = p.value;
+
+ if (symbol.alias == "_global_" || symbol.is("FILE"))
continue;
+ JSDOC.SymbolSet.prototype.walk.apply(this, [symbol]);
+ }
+}
+
+JSDOC.SymbolSet.prototype.walk = function(symbol) {
+ var augments = symbol.augments;
+ for(var i = 0; i < augments.length; i++) {
+ var contributer = this.getSymbol(augments[i]);
+ if (!contributer &&
JSDOC.Lang.isBuiltin(''''+augments[i])) {
+ contributer = new JSDOC.Symbol("_global_."+augments[i], [],
augments[i], new JSDOC.DocComment("Built in."));
+ contributer.isNamespace = true;
+ contributer.srcFile = "";
+ contributer.isPrivate = false;
+ JSDOC.Parser.addSymbol(contributer);
+ }
+
+ if (contributer) {
+ if (contributer.augments.length) {
+ JSDOC.SymbolSet.prototype.walk.apply(this, [contributer]);
+ }
+
+ symbol.inheritsFrom.push(contributer.alias);
+ //if (!isUnique(symbol.inheritsFrom)) {
+ // LOG.warn("Can''t resolve augments: Circular
reference: "+symbol.alias+" inherits from
"+contributer.alias+" more than
once.");
+ //}
+ //else {
+ var cmethods = contributer.methods;
+ var cproperties = contributer.properties;
+
+ for (var ci = 0, cl = cmethods.length; ci < cl; ci++) {
+ if (!cmethods[ci].isStatic) symbol.inherit(cmethods[ci]);
+ }
+ for (var ci = 0, cl = cproperties.length; ci < cl; ci++) {
+ if (!cproperties[ci].isStatic) symbol.inherit(cproperties[ci]);
+ }
+ //}
+ }
+ else LOG.warn("Can''t augment contributer:
"+augments[i]+", not found.");
+ }
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TextStream.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,41 @@
+
+/**
+ @constructor
+*/
+JSDOC.TextStream = function(text) {
+ if (typeof(text) == "undefined") text = "";
+ text = ""+text;
+ this.text = text;
+ this.cursor = 0;
+}
+
+JSDOC.TextStream.prototype.look = function(n) {
+ if (typeof n == "undefined") n = 0;
+
+ if (this.cursor+n < 0 || this.cursor+n >= this.text.length) {
+ var result = new String("");
+ result.eof = true;
+ return result;
+ }
+ return this.text.charAt(this.cursor+n);
+}
+
+JSDOC.TextStream.prototype.next = function(n) {
+ if (typeof n == "undefined") n = 1;
+ if (n < 1) return null;
+
+ var pulled = "";
+ for (var i = 0; i < n; i++) {
+ if (this.cursor+i < this.text.length) {
+ pulled += this.text.charAt(this.cursor+i);
+ }
+ else {
+ var result = new String("");
+ result.eof = true;
+ return result;
+ }
+ }
+
+ this.cursor += n;
+ return pulled;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Token.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,18 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ @constructor
+*/
+JSDOC.Token = function(data, type, name) {
+ this.data = data;
+ this.type = type;
+ this.name = name;
+}
+
+JSDOC.Token.prototype.toString = function() {
+ return "<"+this.type+"
name=\""+this.name+"\">"+this.data+"</"+this.type+">";
+}
+
+JSDOC.Token.prototype.is = function(what) {
+ return this.name === what || this.type === what;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TokenReader.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,332 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ @class Search a {@link JSDOC.TextStream} for language tokens.
+*/
+JSDOC.TokenReader = function() {
+ this.keepDocs = true;
+ this.keepWhite = false;
+ this.keepComments = false;
+}
+
+/**
+ @type {JSDOC.Token[]}
+ */
+JSDOC.TokenReader.prototype.tokenize =
function(/**JSDOC.TextStream*/stream) {
+ var tokens = [];
+ /**@ignore*/ tokens.last = function() { return
tokens[tokens.length-1]; }
+ /**@ignore*/ tokens.lastSym = function() {
+ for (var i = tokens.length-1; i >= 0; i--) {
+ if (!(tokens[i].is("WHIT") || tokens[i].is("COMM")))
return tokens[i];
+ }
+ }
+
+ while (!stream.look().eof) {
+ if (this.read_mlcomment(stream, tokens)) continue;
+ if (this.read_slcomment(stream, tokens)) continue;
+ if (this.read_dbquote(stream, tokens)) continue;
+ if (this.read_snquote(stream, tokens)) continue;
+ if (this.read_regx(stream, tokens)) continue;
+ if (this.read_numb(stream, tokens)) continue;
+ if (this.read_punc(stream, tokens)) continue;
+ if (this.read_newline(stream, tokens)) continue;
+ if (this.read_space(stream, tokens)) continue;
+ if (this.read_word(stream, tokens)) continue;
+
+ // if execution reaches here then an error has happened
+ tokens.push(new JSDOC.Token(stream.next(), "TOKN",
"UNKNOWN_TOKEN"));
+ }
+ return tokens;
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_word =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found = "";
+ while (!stream.look().eof && JSDOC.Lang.isWordChar(stream.look())) {
+ found += stream.next();
+ }
+
+ if (found === "") {
+ return false;
+ }
+ else {
+ var name;
+ if ((name = JSDOC.Lang.keyword(found))) tokens.push(new
JSDOC.Token(found, "KEYW", name));
+ else tokens.push(new JSDOC.Token(found, "NAME", "NAME"));
+ return true;
+ }
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_punc =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found = "";
+ var name;
+ while (!stream.look().eof && JSDOC.Lang.punc(found+stream.look())) {
+ found += stream.next();
+ }
+
+ if (found === "") {
+ return false;
+ }
+ else {
+ tokens.push(new JSDOC.Token(found, "PUNC",
JSDOC.Lang.punc(found)));
+ return true;
+ }
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_space =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found = "";
+
+ while (!stream.look().eof && JSDOC.Lang.isSpace(stream.look())) {
+ found += stream.next();
+ }
+
+ if (found === "") {
+ return false;
+ }
+ else {
+ if (this.collapseWhite) found = " ";
+ if (this.keepWhite) tokens.push(new JSDOC.Token(found, "WHIT",
"SPACE"));
+ return true;
+ }
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_newline =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found = "";
+
+ while (!stream.look().eof && JSDOC.Lang.isNewline(stream.look())) {
+ found += stream.next();
+ }
+
+ if (found === "") {
+ return false;
+ }
+ else {
+ if (this.collapseWhite) found = "\n";
+ if (this.keepWhite) tokens.push(new
JSDOC.Token(found, "WHIT", "NEWLINE"));
+ return true;
+ }
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_mlcomment =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ if (stream.look() == "/" && stream.look(1) == "*")
{
+ var found = stream.next(2);
+
+ while (!stream.look().eof && !(stream.look(-1) == "/"
&& stream.look(-2)
== "*")) {
+ found += stream.next();
+ }
+
+ // to start doclet we allow /** or /*** but not /**/ or /****
+ if (/^\/\*\*([^\/]|\*[^*])/.test(found) && this.keepDocs)
tokens.push(new JSDOC.Token(found, "COMM", "JSDOC"));
+ else if (this.keepComments) tokens.push(new
JSDOC.Token(found, "COMM", "MULTI_LINE_COMM"));
+ return true;
+ }
+ return false;
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_slcomment =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found;
+ if (
+ (stream.look() == "/" && stream.look(1) == "/"
&& (found=stream.next(2)))
+ ||
+ (stream.look() == "<" && stream.look(1) == "!"
&& stream.look(2) == "-"
&& stream.look(3) == "-" && (found=stream.next(4)))
+ ) {
+
+ while (!stream.look().eof && !JSDOC.Lang.isNewline(stream.look())) {
+ found += stream.next();
+ }
+
+ if (this.keepComments) {
+ tokens.push(new JSDOC.Token(found, "COMM",
"SINGLE_LINE_COMM"));
+ }
+ return true;
+ }
+ return false;
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_dbquote =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ if (stream.look() == "\"") {
+ // find terminator
+ var string = stream.next();
+
+ while (!stream.look().eof) {
+ if (stream.look() == "\\") {
+ if (JSDOC.Lang.isNewline(stream.look(1))) {
+ do {
+ stream.next();
+ } while (!stream.look().eof &&
JSDOC.Lang.isNewline(stream.look()));
+ string += "\\\n";
+ }
+ else {
+ string += stream.next(2);
+ }
+ }
+ else if (stream.look() == "\"") {
+ string += stream.next();
+ tokens.push(new JSDOC.Token(string, "STRN",
"DOUBLE_QUOTE"));
+ return true;
+ }
+ else {
+ string += stream.next();
+ }
+ }
+ }
+ return false; // error! unterminated string
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_snquote =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ if (stream.look() == "''") {
+ // find terminator
+ var string = stream.next();
+
+ while (!stream.look().eof) {
+ if (stream.look() == "\\") { // escape sequence
+ string += stream.next(2);
+ }
+ else if (stream.look() == "''") {
+ string += stream.next();
+ tokens.push(new JSDOC.Token(string, "STRN",
"SINGLE_QUOTE"));
+ return true;
+ }
+ else {
+ string += stream.next();
+ }
+ }
+ }
+ return false; // error! unterminated string
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_numb =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ if (stream.look() === "0" && stream.look(1) ==
"x") {
+ return this.read_hex(stream, tokens);
+ }
+
+ var found = "";
+
+ while (!stream.look().eof &&
JSDOC.Lang.isNumber(found+stream.look())){
+ found += stream.next();
+ }
+
+ if (found === "") {
+ return false;
+ }
+ else {
+ if (/^0[0-7]/.test(found)) tokens.push(new
JSDOC.Token(found, "NUMB", "OCTAL"));
+ else tokens.push(new JSDOC.Token(found, "NUMB",
"DECIMAL"));
+ return true;
+ }
+}
+/*t:
+ requires("../lib/JSDOC/TextStream.js");
+ requires("../lib/JSDOC/Token.js");
+ requires("../lib/JSDOC/Lang.js");
+
+ plan(3, "testing JSDOC.TokenReader.prototype.read_numb");
+
+ //// setup
+ var src = "function foo(num){while (num+8.0 >= 0x20 && num
< 0777){}}";
+ var tr = new JSDOC.TokenReader();
+ var tokens = tr.tokenize(new JSDOC.TextStream(src));
+
+ var hexToken, octToken, decToken;
+ for (var i = 0; i < tokens.length; i++) {
+ if (tokens[i].name == "HEX_DEC") hexToken = tokens[i];
+ if (tokens[i].name == "OCTAL") octToken = tokens[i];
+ if (tokens[i].name == "DECIMAL") decToken = tokens[i];
+ }
+ ////
+
+ is(decToken.data, "8.0", "decimal number is found in
source.");
+ is(hexToken.data, "0x20", "hexdec number is found in source
(issue
#99).");
+ is(octToken.data, "0777", "octal number is found in
source.");
+*/
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_hex =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var found = stream.next(2);
+
+ while (!stream.look().eof) {
+ if (JSDOC.Lang.isHexDec(found)
&& !JSDOC.Lang.isHexDec(found+stream.look())) { // done
+ tokens.push(new JSDOC.Token(found, "NUMB", "HEX_DEC"));
+ return true;
+ }
+ else {
+ found += stream.next();
+ }
+ }
+ return false;
+}
+
+/**
+ @returns {Boolean} Was the token found?
+ */
+JSDOC.TokenReader.prototype.read_regx =
function(/**JSDOC.TokenStream*/stream, tokens) {
+ var last;
+ if (
+ stream.look() == "/"
+ &&
+ (
+
+ (
+ !(last = tokens.lastSym()) // there is no last, the regex is the first
symbol
+ ||
+ (
+ !last.is("NUMB")
+ && !last.is("NAME")
+ && !last.is("RIGHT_PAREN")
+ && !last.is("RIGHT_BRACKET")
+ )
+ )
+ )
+ ) {
+ var regex = stream.next();
+
+ while (!stream.look().eof) {
+ if (stream.look() == "\\") { // escape sequence
+ regex += stream.next(2);
+ }
+ else if (stream.look() == "/") {
+ regex += stream.next();
+
+ while (/[gmi]/.test(stream.look())) {
+ regex += stream.next();
+ }
+
+ tokens.push(new JSDOC.Token(regex, "REGX", "REGX"));
+ return true;
+ }
+ else {
+ regex += stream.next();
+ }
+ }
+ // error: unterminated regex
+ }
+ return false;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/TokenStream.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,133 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/**
+ @constructor
+*/
+JSDOC.TokenStream = function(tokens) {
+ this.tokens = (tokens || []);
+ this.rewind();
+}
+
+/**
+ @constructor
+ @private
+*/
+function VoidToken(/**String*/type) {
+ this.toString = function() {return "<VOID
type=\""+type+"\">"};
+ this.is = function(){return false;}
+}
+
+JSDOC.TokenStream.prototype.rewind = function() {
+ this.cursor = -1;
+}
+
+/**
+ @type JSDOC.Token
+*/
+JSDOC.TokenStream.prototype.look = function(/**Number*/n,
/**Boolean*/considerWhitespace) {
+ if (typeof n == "undefined") n = 0;
+
+ if (considerWhitespace == true) {
+ if (this.cursor+n < 0 || this.cursor+n > this.tokens.length) return {};
+ return this.tokens[this.cursor+n];
+ }
+ else {
+ var count = 0;
+ var i = this.cursor;
+
+ while (true) {
+ if (i < 0) return new JSDOC.Token("", "VOID",
"START_OF_STREAM");
+ else if (i > this.tokens.length) return new
JSDOC.Token("", "VOID", "END_OF_STREAM");
+
+ if (i != this.cursor && (this.tokens[i] === undefined ||
this.tokens[i].is("WHIT"))) {
+ if (n < 0) i--; else i++;
+ continue;
+ }
+
+ if (count == Math.abs(n)) {
+ return this.tokens[i];
+ }
+ count++;
+ (n < 0)? i-- : i++;
+ }
+
+ return new JSDOC.Token("", "VOID",
"STREAM_ERROR"); // because null
isn''t an object and caller always expects an object
+ }
+}
+
+/**
+ @type JSDOC.Token|JSDOC.Token[]
+*/
+JSDOC.TokenStream.prototype.next = function(/**Number*/howMany) {
+ if (typeof howMany == "undefined") howMany = 1;
+ if (howMany < 1) return null;
+ var got = [];
+
+ for (var i = 1; i <= howMany; i++) {
+ if (this.cursor+i >= this.tokens.length) {
+ return null;
+ }
+ got.push(this.tokens[this.cursor+i]);
+ }
+ this.cursor += howMany;
+
+ if (howMany == 1) {
+ return got[0];
+ }
+ else return got;
+}
+
+/**
+ @type JSDOC.Token[]
+*/
+JSDOC.TokenStream.prototype.balance = function(/**String*/start,
/**String*/stop) {
+ if (!stop) stop = JSDOC.Lang.matching(start);
+
+ var depth = 0;
+ var got = [];
+ var started = false;
+
+ while ((token = this.look())) {
+ if (token.is(start)) {
+ depth++;
+ started = true;
+ }
+
+ if (started) {
+ got.push(token);
+ }
+
+ if (token.is(stop)) {
+ depth--;
+ if (depth == 0) return got;
+ }
+ if (!this.next()) break;
+ }
+}
+
+JSDOC.TokenStream.prototype.getMatchingToken = function(/**String*/start,
/**String*/stop) {
+ var depth = 0;
+ var cursor = this.cursor;
+
+ if (!start) {
+ start = JSDOC.Lang.matching(stop);
+ depth = 1;
+ }
+ if (!stop) stop = JSDOC.Lang.matching(start);
+
+ while ((token = this.tokens[cursor])) {
+ if (token.is(start)) {
+ depth++;
+ }
+
+ if (token.is(stop) && cursor) {
+ depth--;
+ if (depth == 0) return this.tokens[cursor];
+ }
+ cursor++;
+ }
+}
+
+JSDOC.TokenStream.prototype.insertAhead = function(/**JSDOC.Token*/token) {
+ this.tokens.splice(this.cursor+1, 0, token);
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Util.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,32 @@
+/**
+ * @namespace
+ * @deprecated Use {@link FilePath} instead.
+ */
+JSDOC.Util = {
+}
+
+/**
+ * @deprecated Use {@link FilePath.fileName} instead.
+ */
+JSDOC.Util.fileName = function(path) {
+ LOG.warn("JSDOC.Util.fileName is deprecated. Use FilePath.fileName
instead.");
+ var nameStart = Math.max(path.lastIndexOf("/")+1,
path.lastIndexOf("\\")+1, 0);
+ return path.substring(nameStart);
+}
+
+/**
+ * @deprecated Use {@link FilePath.fileExtension} instead.
+ */
+JSDOC.Util.fileExtension = function(filename) {
+ LOG.warn("JSDOC.Util.fileExtension is deprecated. Use
FilePath.fileExtension instead.");
+ return filename.split(".").pop().toLowerCase();
+};
+
+/**
+ * @deprecated Use {@link FilePath.dir} instead.
+ */
+JSDOC.Util.dir = function(path) {
+ LOG.warn("JSDOC.Util.dir is deprecated. Use FilePath.dir instead.");
+ var nameStart = Math.max(path.lastIndexOf("/")+1,
path.lastIndexOf("\\")+1, 0);
+ return path.substring(0, nameStart-1);
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC/Walker.js Sun Aug 16 17:18:10
2009
@@ -0,0 +1,473 @@
+if (typeof JSDOC == "undefined") JSDOC = {};
+
+/** @constructor */
+JSDOC.Walker = function(/**JSDOC.TokenStream*/ts) {
+ this.init();
+ if (typeof ts != "undefined") {
+ this.walk(ts);
+ }
+}
+
+JSDOC.Walker.prototype.init = function() {
+ this.ts = null;
+
+ var globalSymbol = new JSDOC.Symbol("_global_", [],
"GLOBAL", new
JSDOC.DocComment(""));
+ globalSymbol.isNamespace = true;
+ globalSymbol.srcFile = "";
+ globalSymbol.isPrivate = false;
+ JSDOC.Parser.addSymbol(globalSymbol);
+ this.lastDoc = null;
+ this.token = null;
+
+ /**
+ The chain of symbols under which we are currently nested.
+ @type Array
+ */
+ this.namescope = [globalSymbol];
+ this.namescope.last = function(n){ if (!n) n = 0; return
this[this.length-(1+n)] || "" };
+}
+
+JSDOC.Walker.prototype.walk = function(/**JSDOC.TokenStream*/ts) {
+ this.ts = ts;
+ while (this.token = this.ts.look()) {
+ if (this.token.popNamescope) {
+
+ var symbol = this.namescope.pop();
+ if (symbol.is("FUNCTION")) {
+ if (this.ts.look(1).is("LEFT_PAREN") &&
symbol.comment.getTag("function").length == 0) {
+ symbol.isa = "OBJECT";
+ }
+ }
+ }
+ this.step();
+ if (!this.ts.next()) break;
+ }
+}
+
+JSDOC.Walker.prototype.step = function() {
+ if (this.token.is("JSDOC")) { // it''s a doc comment
+
+ var doc = new JSDOC.DocComment(this.token.data);
+
+
+ if (doc.getTag("exports").length > 0) {
+ var exports = doc.getTag("exports")[0];
+
+ exports.desc.match(/(\S+) as (\S+)/i);
+ var n1 = RegExp.$1;
+ var n2 = RegExp.$2;
+
+ if (!n1 && n2) throw "@exports tag requires a value like:
''name as
ns.name''";
+
+ JSDOC.Parser.rename = (JSDOC.Parser.rename || {});
+ JSDOC.Parser.rename[n1] = n2
+ }
+
+ if (doc.getTag("lends").length > 0) {
+ var lends = doc.getTag("lends")[0];
+
+ var name = lends.desc
+ if (!name) throw "@lends tag requires a value.";
+
+ var symbol = new JSDOC.Symbol(name, [], "OBJECT", doc);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+
+ this.lastDoc = null;
+ return true;
+ }
+ else if (doc.getTag("name").length > 0 &&
doc.getTag("overview").length
== 0) { // it''s a virtual symbol
+ var virtualName = doc.getTag("name")[0].desc;
+ if (!virtualName) throw "@name tag requires a value.";
+
+ var symbol = new JSDOC.Symbol(virtualName, [], "VIRTUAL", doc);
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.lastDoc = null;
+ return true;
+ }
+ else if (doc.meta) { // it''s a meta doclet
+ if (doc.meta == "@+") JSDOC.DocComment.shared = doc.src;
+ else if (doc.meta == "@-") JSDOC.DocComment.shared = "";
+ else if (doc.meta == "nocode+") JSDOC.Parser.conf.ignoreCode =
true;
+ else if (doc.meta == "nocode-") JSDOC.Parser.conf.ignoreCode =
JSDOC.opt.n;
+ else throw "Unrecognized meta comment: "+doc.meta;
+
+ this.lastDoc = null;
+ return true;
+ }
+ else if (doc.getTag("overview").length > 0) { // it''s a
file overview
+ symbol = new JSDOC.Symbol("", [], "FILE", doc);
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.lastDoc = null;
+ return true;
+ }
+ else {
+ this.lastDoc = doc;
+ return false;
+ }
+ }
+ else if (!JSDOC.Parser.conf.ignoreCode) { // it''s code
+ if (this.token.is("NAME")) {
+ var symbol;
+ var name = this.token.data;
+ var doc = null; if (this.lastDoc) doc = this.lastDoc;
+ var params = [];
+
+ // it''s inside an anonymous object
+ if (this.ts.look(1).is("COLON") &&
this.ts.look(-1).is("LEFT_CURLY")
&& !(this.ts.look(-2).is("JSDOC") ||
this.namescope.last().comment.getTag("lends").length ||
this.ts.look(-2).is("ASSIGN") ||
this.ts.look(-2).is("COLON"))) {
+ name = "$anonymous";
+ name = this.namescope.last().alias+"-"+name
+
+ params = [];
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken(null, "RIGHT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // function foo() {}
+ else if (this.ts.look(-1).is("FUNCTION") &&
this.ts.look(1).is("LEFT_PAREN")) {
+ var isInner;
+
+ if (this.lastDoc) doc = this.lastDoc;
+ name = this.namescope.last().alias+"-"+name;
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+
+ params = JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+
+ symbol = new JSDOC.Symbol(name, params, "FUNCTION", doc);
+ if (isInner) symbol.isInner = true;
+
+ if (this.ts.look(1).is("JSDOC")) {
+ var inlineReturn = ""+this.ts.look(1).data;
+ inlineReturn = inlineReturn.replace(/(^\/\*\* *| *\*\/$)/g, "");
+ symbol.type = inlineReturn;
+ }
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // foo = function() {}
+ else if (this.ts.look(1).is("ASSIGN") &&
this.ts.look(2).is("FUNCTION")) {
+ var isInner;
+ if (this.ts.look(-1).is("VAR") || this.isInner) {
+ name = this.namescope.last().alias+"-"+name
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+ }
+ else if (name.indexOf("this.") == 0) {
+ name = this.resolveThis(name);
+ }
+
+ if (this.lastDoc) doc = this.lastDoc;
+ params = JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+
+ symbol = new JSDOC.Symbol(name, params, "FUNCTION", doc);
+ if (isInner) symbol.isInner = true;
+
+ if (this.ts.look(1).is("JSDOC")) {
+ var inlineReturn = ""+this.ts.look(1).data;
+ inlineReturn = inlineReturn.replace(/(^\/\*\* *| *\*\/$)/g, "");
+ symbol.type = inlineReturn;
+ }
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // foo = new function() {}
+ else if (this.ts.look(1).is("ASSIGN") &&
this.ts.look(2).is("NEW") &&
this.ts.look(3).is("FUNCTION")) {
+ var isInner;
+ if (this.ts.look(-1).is("VAR") || this.isInner) {
+ name = this.namescope.last().alias+"-"+name
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+ }
+ else if (name.indexOf("this.") == 0) {
+ name = this.resolveThis(name);
+ }
+
+ if (this.lastDoc) doc = this.lastDoc;
+ params = JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+ if (isInner) symbol.isInner = true;
+
+ if (this.ts.look(1).is("JSDOC")) {
+ var inlineReturn = ""+this.ts.look(1).data;
+ inlineReturn = inlineReturn.replace(/(^\/\*\* *| *\*\/$)/g, "");
+ symbol.type = inlineReturn;
+ }
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ symbol.scopeType = "INSTANCE";
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // foo: function() {}
+ else if (this.ts.look(1).is("COLON") &&
this.ts.look(2).is("FUNCTION"))
{
+ name =
(this.namescope.last().alias+"."+name).replace("#.",
"#");
+
+ if (this.lastDoc) doc = this.lastDoc;
+ params = JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+
+ if (doc && doc.getTag("constructs").length) {
+ name = name.replace(/\.prototype(\.|$)/, "#");
+
+ if (name.indexOf("#") > -1) name = name.match(/(^[^#]+)/)[0];
+ else name = this.namescope.last().alias;
+
+ symbol = new JSDOC.Symbol(name, params, "CONSTRUCTOR", doc);
+ }
+ else {
+ symbol = new JSDOC.Symbol(name, params, "FUNCTION", doc);
+ }
+
+ if (this.ts.look(1).is("JSDOC")) {
+ var inlineReturn = ""+this.ts.look(1).data;
+ inlineReturn = inlineReturn.replace(/(^\/\*\* *| *\*\/$)/g, "");
+ symbol.type = inlineReturn;
+ }
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // foo = {}
+ else if (this.ts.look(1).is("ASSIGN") &&
this.ts.look(2).is("LEFT_CURLY")) {
+ var isInner;
+ if (this.ts.look(-1).is("VAR") || this.isInner) {
+ name = this.namescope.last().alias+"-"+name
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+ }
+ else if (name.indexOf("this.") == 0) {
+ name = this.resolveThis(name);
+ }
+
+ if (this.lastDoc) doc = this.lastDoc;
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+ if (isInner) symbol.isInner = true;
+
+
+ if (doc) JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // var foo;
+ else if (this.ts.look(1).is("SEMICOLON")) {
+ var isInner;
+ if (this.ts.look(-1).is("VAR") || this.isInner) {
+ name = this.namescope.last().alias+"-"+name
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+
+ if (this.lastDoc) doc = this.lastDoc;
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+ if (isInner) symbol.isInner = true;
+
+
+ if (doc) JSDOC.Parser.addSymbol(symbol);
+ }
+ }
+ // foo = x
+ else if (this.ts.look(1).is("ASSIGN")) {
+
+ var isInner;
+ if (this.ts.look(-1).is("VAR") || this.isInner) {
+ name = this.namescope.last().alias+"-"+name
+ if (!this.namescope.last().is("GLOBAL")) isInner = true;
+ }
+ else if (name.indexOf("this.") == 0) {
+ name = this.resolveThis(name);
+ }
+
+ if (this.lastDoc) doc = this.lastDoc;
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+ if (isInner) symbol.isInner = true;
+
+
+ if (doc) JSDOC.Parser.addSymbol(symbol);
+ }
+ // foo: {}
+ else if (this.ts.look(1).is("COLON") &&
this.ts.look(2).is("LEFT_CURLY")) {
+ name =
(this.namescope.last().alias+"."+name).replace("#.",
"#");
+
+ if (this.lastDoc) doc = this.lastDoc;
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+
+
+ if (doc) JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ // foo: x
+ else if (this.ts.look(1).is("COLON")) {
+ name =
(this.namescope.last().alias+"."+name).replace("#.",
"#");;
+
+ if (this.lastDoc) doc = this.lastDoc;
+
+ symbol = new JSDOC.Symbol(name, params, "OBJECT", doc);
+
+
+ if (doc) JSDOC.Parser.addSymbol(symbol);
+ }
+ // foo(...)
+ else if (this.ts.look(1).is("LEFT_PAREN")) {
+ if (typeof JSDOC.PluginManager != "undefined") {
+ var functionCall = {name: name};
+
+ var cursor = this.ts.cursor;
+ params =
JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+ this.ts.cursor = cursor;
+
+ for (var i = 0; i < params.length; i++)
+ functionCall["arg" + (i + 1)] = params[i].name;
+
+ JSDOC.PluginManager.run("onFunctionCall", functionCall);
+ if (functionCall.doc) {
+ this.ts.insertAhead(new
JSDOC.Token(functionCall.doc, "COMM", "JSDOC"));
+ }
+ }
+ }
+ this.lastDoc = null;
+ }
+ else if (this.token.is("FUNCTION")) { // it''s an anonymous
function
+ if (
+ (!this.ts.look(-1).is("COLON") ||
!this.ts.look(-1).is("ASSIGN"))
+ && !this.ts.look(1).is("NAME")
+ ) {
+ if (this.lastDoc) doc = this.lastDoc;
+
+ name = "$anonymous";
+ name = this.namescope.last().alias+"-"+name
+
+ params = JSDOC.Walker.onParamList(this.ts.balance("LEFT_PAREN"));
+
+ symbol = new JSDOC.Symbol(name, params, "FUNCTION", doc);
+
+
+ JSDOC.Parser.addSymbol(symbol);
+
+ this.namescope.push(symbol);
+
+ var matching = this.ts.getMatchingToken("LEFT_CURLY");
+ if (matching) matching.popNamescope = name;
+ else LOG.warn("Mismatched } character. Can''t parse code in
file " +
symbol.srcFile + ".");
+ }
+ }
+ }
+ return true;
+}
+
+/**
+ Resolves what "this." means when it appears in a name.
+ @param name The name that starts with "this.".
+ @returns The name with "this." resolved.
+ */
+JSDOC.Walker.prototype.resolveThis = function(name) {
+ name.match(/^this\.(.+)$/)
+ var nameFragment = RegExp.$1;
+ if (!nameFragment) return name;
+
+ var symbol = this.namescope.last();
+ var scopeType = symbol.scopeType || symbol.isa;
+
+ // if we are in a constructor function, `this` means the instance
+ if (scopeType == "CONSTRUCTOR") {
+ name = symbol.alias+"#"+nameFragment;
+ }
+
+ // if we are in an anonymous constructor function, `this` means the
instance
+ else if (scopeType == "INSTANCE") {
+ name = symbol.alias+"."+nameFragment;
+ }
+
+ // if we are in a function, `this` means the container (possibly the
global)
+ else if (scopeType == "FUNCTION") {
+ // in a method of a prototype, so `this` means the constructor
+ if (symbol.alias.match(/(^.*)[#.-][^#.-]+/)) {
+ var parentName = RegExp.$1;
+ var parent = JSDOC.Parser.symbols.getSymbol(parentName);
+
+ if (!parent) {
+ if (JSDOC.Lang.isBuiltin(parentName)) parent =
JSDOC.Parser.addBuiltin(parentName);
+ else {
+ if (symbol.alias.indexOf("$anonymous") < 0) // these will be
ignored
eventually
+ LOG.warn("Trying to document "+symbol.alias+" without
first
documenting "+parentName+".");
+ }
+ }
+ if (parent) name =
parentName+(parent.is("CONSTRUCTOR")?"#":".")+nameFragment;
+ }
+ else {
+ parent = this.namescope.last(1);
+ name =
parent.alias+(parent.is("CONSTRUCTOR")?"#":".")+nameFragment;
+ }
+ }
+ // otherwise it means the global
+ else {
+ name = nameFragment;
+ }
+
+ return name;
+}
+
+JSDOC.Walker.onParamList = function(/**Array*/paramTokens) {
+ if (!paramTokens) {
+ LOG.warn("Malformed parameter list. Can''t parse code.");
+ return [];
+ }
+ var params = [];
+ for (var i = 0, l = paramTokens.length; i < l; i++) {
+ if (paramTokens[i].is("JSDOC")) {
+ var paramType = paramTokens[i].data.replace(/(^\/\*\* *| *\*\/$)/g,
"");
+
+ if (paramTokens[i+1] && paramTokens[i+1].is("NAME")) {
+ i++;
+ params.push({type: paramType, name: paramTokens[i].data});
+ }
+ }
+ else if (paramTokens[i].is("NAME")) {
+ params.push({name: paramTokens[i].data});
+ }
+ }
+ return params;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/lib/JSDOC.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,103 @@
+/**
+ @overview
+ @date $Date: 2009-05-09 13:18:50 +0100 (Sat, 09 May 2009) $
+ @version $Revision: 788 $
+ @location $HeadURL:
https://jsdoc-toolkit.googlecode.com/svn/trunk/jsdoc-toolkit/app/lib/JSDOC.js
$
+ @name JSDOC.js
+ */
+
+/**
+ This is the main container for the JSDOC application.
+ @namespace
+*/
+JSDOC = {
+};
+
+/**
+ @requires Opt
+ */
+if (typeof arguments == "undefined") arguments = [];
+JSDOC.opt = Opt.get(
+ arguments,
+ {
+ d: "directory",
+ c: "conf",
+ t: "template",
+ r: "recurse",
+ x: "ext",
+ p: "private",
+ a: "allfunctions",
+ e: "encoding",
+ n: "nocode",
+ o: "out",
+ s: "suppress",
+ S: "securemodules",
+ q: "quiet",
+ T: "testmode",
+ h: "help",
+ v: "verbose",
+ "D[]": "define",
+ "E[]": "exclude",
+ "H[]": "handler"
+ }
+);
+
+/** The current version string of this application. */
+JSDOC.VERSION = "2.1.1";
+
+/** Print out usage information and quit. */
+JSDOC.usage = function() {
+ print("USAGE: java -jar jsrun.jar app/run.js [OPTIONS] <SRC_DIR>
<SRC_FILE> ...");
+ print("");
+ print("OPTIONS:");
+ print(" -a or --allfunctions\n Include all functions, even
undocumented ones.\n");
+ print(" -c or --conf\n Load a configuration file.\n");
+ print(" -d=<PATH> or --directory=<PATH>\n Output to
this
directory (defaults to \"out\").\n");
+ print(" -D=\"myVar:My value\" or --define=\"myVar:My
value\"\n
Multiple. Define a variable, available in JsDoc as JSDOC.opt.D.myVar.\n");
+ print(" -e=<ENCODING> or --encoding=<ENCODING>\n
Use this
encoding to read and write files.\n");
+ print(" -E=\"REGEX\" or --exclude=\"REGEX\"\n
Multiple. Exclude
files based on the supplied regex.\n");
+ print(" -h or --help\n Show this message and exit.\n");
+ print(" -n or --nocode\n Ignore all code, only document
comments with @name tags.\n");
+ print(" -o=<PATH> or --out=<PATH>\n Print log
messages to a
file (defaults to stdout).\n");
+ print(" -p or --private\n Include symbols tagged as private,
underscored and inner symbols.\n");
+ print(" -q or --quiet\n Do not output any messages, not even
warnings.\n");
+ print(" -r=<DEPTH> or --recurse=<DEPTH>\n Descend
into src
directories.\n");
+ print(" -s or --suppress\n Suppress source code
output.\n");
+ print(" -S or --securemodules\n Use Secure Modules mode to
parse source code.\n");
+ print(" -t=<PATH> or --template=<PATH>\n Required.
Use this
template to format the output.\n");
+ print(" -T or --test\n Run all unit tests and exit.\n");
+ print(" -v or --verbose\n Provide verbose feedback about what
is happening.\n");
+ print(" -x=<EXT>[,EXT]... or --ext=<EXT>[,EXT]...\n
Scan source
files with the given extension/s (defaults to js).\n");
+
+ quit();
+}
+
+/*t:
+ plan(4, "Testing JSDOC namespace.");
+
+ is(
+ typeof JSDOC,
+ "object",
+ "JSDOC.usage is a function."
+ );
+
+ is(
+ typeof JSDOC.VERSION,
+ "string",
+ "JSDOC.VERSION is a string."
+ );
+
+ is(
+ typeof JSDOC.usage,
+ "function",
+ "JSDOC.usage is a function."
+ );
+
+ is(
+ typeof JSDOC.opt,
+ "object",
+ "JSDOC.opt is a object."
+ );
+ */
+
+if (this.IO) IO.includeDir("lib/JSDOC/");
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/main.js Sun Aug 16 17:18:10 2009
@@ -0,0 +1,111 @@
+/**
+ * @version $Id: main.js 769 2009-01-11 12:13:00Z micmath $
+ */
+
+function main() {
+ IO.include("lib/JSDOC.js");
+ IO.includeDir("plugins/");
+
+ // process the options
+
+ // the -c option: options are defined in a configuration file
+ if (JSDOC.opt.c) {
+ eval("JSDOC.conf = " + IO.readFile(JSDOC.opt.c));
+
+ LOG.inform("Using configuration file at
''"+JSDOC.opt.c+"''.");
+
+ for (var c in JSDOC.conf) {
+ if (c !== "D" && !defined(JSDOC.opt[c])) { // commandline
overrules
config file
+ JSDOC.opt[c] = JSDOC.conf[c];
+ }
+ }
+
+ if (typeof JSDOC.conf["_"] != "undefined") {
+ JSDOC.opt["_"] =
JSDOC.opt["_"].concat(JSDOC.conf["_"]);
+ }
+
+ LOG.inform("With configuration: ");
+ for (var o in JSDOC.opt) {
+ LOG.inform(" "+o+": "+JSDOC.opt[o]);
+ }
+ }
+
+ // be verbose
+ if (JSDOC.opt.v) LOG.verbose = true;
+
+ // send log messages to a file
+ if (JSDOC.opt.o) LOG.out = IO.open(JSDOC.opt.o);
+
+ // run the unit tests
+ if (JSDOC.opt.T) {
+ LOG.inform("JsDoc Toolkit running in test mode at "+new
Date()+".");
+ IO.include("frame/Testrun.js");
+ IO.include("test.js");
+ }
+ else {
+ // a template must be defined and must be a directory path
+ if (!JSDOC.opt.t &&
System.getProperty("jsdoc.template.dir")) {
+ JSDOC.opt.t = System.getProperty("jsdoc.template.dir");
+ }
+ if (JSDOC.opt.t
&& !JSDOC.opt.t.charAt(JSDOC.opt.t.length-1).match(/[\\\/]/)) {
+ JSDOC.opt.t += SYS.slash;
+ }
+
+ // verbose messages about the options we were given
+ LOG.inform("JsDoc Toolkit main() running at "+new
Date()+".");
+ LOG.inform("With options: ");
+ for (var o in JSDOC.opt) {
+ LOG.inform(" "+o+": "+JSDOC.opt[o]);
+ }
+
+ // initialize and build a symbolSet from your code
+ JSDOC.JsDoc();
+
+ // debugger''s option: dump the entire symbolSet produced from your
code
+ if (JSDOC.opt.Z) {
+ LOG.warn("So you want to see the data structure, eh? This might hang if
you have circular refs...");
+ IO.include("frame/Dumper.js");
+ var symbols = JSDOC.JsDoc.symbolSet.toArray();
+ for (var i = 0, l = symbols.length; i < l; i++) {
+ var symbol = symbols[i];
+ print("// symbol: " + symbol.alias);
+ print(symbol.serialize());
+ }
+ }
+ else {
+ if (typeof JSDOC.opt.t != "undefined") {
+ try {
+ // a file named "publish.js" must exist in the template
directory
+ load(JSDOC.opt.t+"publish.js");
+
+ // and must define a function named "publish"
+ if (!publish) {
+ LOG.warn("No publish() function is defined in that template so
nothing to do.");
+ }
+ else {
+ // which will be called with the symbolSet produced from your code
+ publish(JSDOC.JsDoc.symbolSet);
+ }
+ }
+ catch(e) {
+ LOG.warn("Sorry, that doesn''t seem to be a valid
template: "+JSDOC.opt.t+"publish.js : "+e);
+ }
+ }
+ else {
+ LOG.warn("No template or handlers given. Might as well read the usage
notes.");
+ JSDOC.usage();
+ }
+ }
+ }
+
+ // notify of any warnings
+ if (!JSDOC.opt.q && LOG.warnings.length) {
+ print(LOG.warnings.length+" warning"+(LOG.warnings.length !=
1? "s":"")+".");
+ }
+
+ // stop sending log messages to a file
+ if (LOG.out) {
+ LOG.out.flush();
+ LOG.out.close();
+ }
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/plugins/commentSrcJson.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,20 @@
+JSDOC.PluginManager.registerPlugin(
+ "JSDOC.commentSrcJson",
+ {
+ onDocCommentSrc: function(comment) {
+ var json;
+ if (/^\s*@json\b/.test(comment)) {
+ comment.src = new String(comment.src).replace("@json",
"");
+
+ eval("json = "+comment.src);
+ var tagged = "";
+ for (var i in json) {
+ var tag = json[i];
+ // todo handle cases where tag is an object
+ tagged += "@"+i+" "+tag+"\n";
+ }
+ comment.src = tagged;
+ }
+ }
+ }
+);
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/plugins/frameworkPrototype.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,16 @@
+JSDOC.PluginManager.registerPlugin(
+ "JSDOC.frameworkPrototype",
+ {
+ onPrototypeClassCreate: function(classCreator) {
+ var desc = "";
+ if (classCreator.comment) {
+ desc = classCreator.comment;
+ }
+ var insert = desc+"/**
@name "+classCreator.name+"\n at constructor\n at scope
"+classCreator.name+".prototype
*/"
+
+ insert = insert.replace(/\*\/\/\*\*/g, "\n");
+ /*DEBUG*///print("insert is "+insert);
+ classCreator.addComment.data = insert;
+ }
+ }
+);
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/plugins/functionCall.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,10 @@
+JSDOC.PluginManager.registerPlugin(
+ "JSDOC.functionCall",
+ {
+ onFunctionCall: function(functionCall) {
+ if (functionCall.name == "dojo.define" &&
functionCall.arg1) {
+ functionCall.doc = "/** @lends
"+eval(functionCall.arg1)+".prototype
*/";
+ }
+ }
+ }
+);
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/plugins/publishSrcHilite.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,62 @@
+JSDOC.PluginManager.registerPlugin(
+ "JSDOC.publishSrcHilite",
+ {
+ onPublishSrc: function(src) {
+ if (src.path in JsHilite.cache) {
+ return; // already generated src code
+ }
+ else JsHilite.cache[src.path] = true;
+
+ try {
+ var sourceCode = IO.readFile(src.path);
+ }
+ catch(e) {
+ print(e.message);
+ quit();
+ }
+
+ var hiliter = new JsHilite(sourceCode, src.charset);
+ src.hilited = hiliter.hilite();
+ }
+ }
+);
+
+function JsHilite(src, charset) {
+
+ var tr = new JSDOC.TokenReader();
+
+ tr.keepComments = true;
+ tr.keepDocs = true;
+ tr.keepWhite = true;
+
+ this.tokens = tr.tokenize(new JSDOC.TextStream(src));
+
+ // TODO is redefining toString() the best way?
+ JSDOC.Token.prototype.toString = function() {
+ return "<span
class=\""+this.type+"\">"+this.data.replace(/</g,
"<")+"</span>";
+ }
+
+ if (!charset) charset = "utf-8";
+
+ this.header = ''<html><head><meta
http-equiv="content-type"
content="text/html; charset=''+charset+''">
''+
+ "<style>\n\
+ .KEYW {color: #933;}\n\
+ .COMM {color: #bbb; font-style: italic;}\n\
+ .NUMB {color: #393;}\n\
+ .STRN {color: #393;}\n\
+ .REGX {color: #339;}\n\
+ .line {border-right: 1px dotted #666; color: #666; font-style: normal;}\n\
+ </style></head><body><pre>";
+ this.footer = "</pre></body></html>";
+ this.showLinenumbers = true;
+}
+
+JsHilite.cache = {};
+
+JsHilite.prototype.hilite = function() {
+ var hilited = this.tokens.join("");
+ var line = 1;
+ if (this.showLinenumbers) hilited = hilited.replace(/(^|\n)/g,
function(m){return m+"<span
class=''line''>"+((line<10)? "
":"")+((line<100)? "
":"")+(line++)+"</span> "});
+
+ return this.header+hilited+this.footer;
+}
======================================--- /dev/null
+++ /trunk/tools/jsdoc-toolkit/app/plugins/symbolLink.js Sun Aug 16
17:18:10 2009
@@ -0,0 +1,9 @@
+JSDOC.PluginManager.registerPlugin(
+ "JSDOC.symbolLink",
+ {
+ onSymbolLink: function(link) {
+ // modify link.linkPath
+ // or link.linkText here
+ }
+ }
+);
======================================***Additional files exist in this
changeset.***