Merge remote-tracking branch 'upstream/master' into type-refactor

README.md

@@ -24,7 +24,7 @@ and run the following command on Windows:
 If you can't get the short-form commands to work, try invoking Java directly:
 
     java -cp lib/js.jar org.mozilla.javascript.tools.shell.Main \
-    -modules node_modules -modules rhino_modules -modules . \
+    -modules nodejs_modules -modules rhino_modules -modules . \
     jsdoc.js -T
 
 Usage
@@ -72,7 +72,7 @@ or the long form version:
 
     $ java -classpath lib/js.jar \
     org.mozilla.javascript.tools.debugger.Main -debug \
-    -modules node_modules -modules rhino_modules -modules . \
+    -modules nodejs_modules -modules rhino_modules -modules . \
     jsdoc.js \
     your/script.js
 

jsdoc

@@ -25,9 +25,9 @@ fi
 if test "$1" = "-T"
 then
     echo "Running Tests"
-    java -classpath "${BASEPATH}/lib/js.jar" ${CMD} -opt -1 -modules "${URLPATH}/node_modules" -modules "${URLPATH}/rhino_modules" -modules "${URLPATH}" "${BASEPATH}/jsdoc.js" $ARGS --dirname="${BASEPATH}/" 
+    java -classpath "${BASEPATH}/lib/js.jar" ${CMD} -opt -1 -modules "${URLPATH}/nodejs_modules" -modules "${URLPATH}/rhino_modules" -modules "${URLPATH}" "${BASEPATH}/jsdoc.js" $ARGS --dirname="${BASEPATH}/" 
 
 else
     # normal mode should be quiet
-    java -classpath "${BASEPATH}/lib/js.jar" ${CMD} -modules "${URLPATH}/node_modules" -modules "${URLPATH}/rhino_modules" -modules "${URLPATH}" "${BASEPATH}/jsdoc.js" $ARGS --dirname="${BASEPATH}/" 
+    java -classpath "${BASEPATH}/lib/js.jar" ${CMD} -modules "${URLPATH}/nodejs_modules" -modules "${URLPATH}/rhino_modules" -modules "${URLPATH}" "${BASEPATH}/jsdoc.js" $ARGS --dirname="${BASEPATH}/" 
 fi

jsdoc.cmd

@@ -36,10 +36,10 @@ IF [%1]==[--debug] (
 
 IF [%1]==[-T] (
     ECHO Running Tests
-    java -classpath "%_BASEPATH%/lib/js.jar" %CMD% -opt -1 -modules "%_URLPATH%/node_modules" -modules "%_URLPATH%/rhino_modules" -modules "%_URLPATH%" "%_BASEPATH%/jsdoc.js" %ARGS% --dirname="%_BASEPATH%/
+    java -classpath "%_BASEPATH%/lib/js.jar" %CMD% -opt -1 -modules "%_URLPATH%/nodejs_modules" -modules "%_URLPATH%/rhino_modules" -modules "%_URLPATH%" "%_BASEPATH%/jsdoc.js" %ARGS% --dirname="%_BASEPATH%/
 ) ELSE (
     REM normal mode should be quiet
-    java -classpath "%_BASEPATH%/lib/js.jar" %CMD% -modules "%_URLPATH%/node_modules" -modules "%_URLPATH%/rhino_modules" -modules "%_URLPATH%" "%_BASEPATH%/jsdoc.js" %ARGS% --dirname="%_BASEPATH%/
+    java -classpath "%_BASEPATH%/lib/js.jar" %CMD% -modules "%_URLPATH%/nodejs_modules" -modules "%_URLPATH%/rhino_modules" -modules "%_URLPATH%" "%_BASEPATH%/jsdoc.js" %ARGS% --dirname="%_BASEPATH%/
 )
 
 ENDLOCAL

package.json

@@ -1,7 +1,7 @@
 {
 	"name": "JSDoc",
 	"version": "3.0.0",
-	"revision": "1339743348712",
+	"revision": "1345064014682",
 	"description": "An automatic documentation generator for javascript.",
 	"keywords": [ "documentation", "javascript" ],
 	"licenses": [
@@ -29,10 +29,6 @@
         {
             "name": "Jannon Frank",
             "email": "jannon@jannon.net"
-        },
-        {
-            "name": "Jeff Williams",
-            "email": "jeffrey.l.williams@gmail.com"
         }
     ],
 	"maintainers": [

plugins/partial.js

@@ -0,0 +1,30 @@
+/**
+    @overview Adds support for reusable partial jsdoc files.
+    @module plugins/partial
+    @author Ludo Antonov <ludo@hulu.com>
+ */
+
+var fs = require('fs');
+var path = require('path');
+
+exports.handlers = {
+    ///
+    /// Include a partial jsdoc
+    /// @param e
+    /// @param e.filename
+    /// @param e.source
+    ///
+    /// @example
+    ///     @partial "partial_doc.jsdoc"
+    ///
+    beforeParse: function(e) {
+        e.source = e.source.replace(/(@partial \".*\")+/g, function($) {
+            var pathArg = $.match(/\".*\"/)[0].replace(/"/g,'');
+            var fullPath =  path.join(e.filename , '..', pathArg);
+
+            var partialData = fs.readFileSync(fullPath);
+
+            return partialData;
+        });
+    }
+};

plugins/test/specs/verboseOutput.js

@@ -0,0 +1,17 @@
+/**
+ * @author Rob Taylor [manix84@gmail.com]
+ */
+
+describe("verbose output plugin", function () {
+    var parser = new (require("jsdoc/src/parser")).Parser(),
+        plugin = require('plugins/verboseOutput'),
+        docSet;
+
+    installPlugins(['plugins/verboseOutput'], parser);
+    docSet = jasmine.getDocSetFromFile("plugins/verboseOutput.js", parser);
+
+    it("should log file names to console", function() {
+        var fileBegin = docSet.getByLongname("module:plugins/verboseOutput.handlers.fileBegin");
+        expect(fileBegin[0].description).toEqual("Logging the file name to the console.");
+    });
+});

plugins/verboseOutput.js

@@ -0,0 +1,15 @@
+/**
+ * Adds a verbose output to the console, so that you can see what's happening in your process.
+ * @module plugins/verboseOutput
+ * @author Rob Taylor <manix84@gmail.com> - The basic idea
+ * @author Michael Mathews <micmath@gmail.com> - Wrote the first itteration with me :)
+ */
+
+exports.handlers = {
+    /**
+     * Logging the file name to the console.
+     */
+    fileBegin: function (data) {
+        console.log(data.filename);
+    }
+};

rhino_modules/jsdoc/src/parser.js

@@ -224,7 +224,8 @@ function aboutNode(node) {
             about.type = 'undefined';
         }
     }
-    else if (node.type === Token.ASSIGN || node.type === Token.COLON) {
+    else if (node.type === Token.ASSIGN || node.type === Token.COLON ||
+             node.type === Token.GET || node.type === Token.SET) {
         about.name = nodeToString(node.left);
         if (node.type === Token.COLON) {
 
@@ -235,7 +236,13 @@ function aboutNode(node) {
         }
         about.node = node.right;
         about.value = nodeToString(about.node);
-        about.type = getTypeName(node.right);
+
+        // Getter and setter functions should be treated as properties
+        if (node.type === Token.GET || node.type === Token.SET) {
+            about.type = getTypeName(node);
+        } else {
+            about.type = getTypeName(node.right);
+        }
 
         if (about.type === 'FUNCTION' && about.node.name) {
             about.node.type = tkn.NAMEDFUNCTIONSTATEMENT;
@@ -363,6 +370,18 @@ function visitNode(node) {
             finishers: [currentParser.addDocletRef, currentParser.resolveEnum]
         };
     }
+    else if (node.type === Token.GET || node.type === Token.SET) { // assignment within an object literal
+        e = {
+            id: 'astnode'+node.hashCode(), // the id of the GET/SET node
+            comment: String(node.left.getJsDoc()||'@undocumented'),
+            lineno: node.left.getLineno(),
+            filename: currentSourceName,
+            astnode: node,
+            code: aboutNode(node),
+            event: "symbolFound",
+            finishers: [currentParser.addDocletRef]
+        };
+    }
     else if (node.type == Token.VAR || node.type == Token.LET || node.type == Token.CONST) {
 
         if (node.variables) {

test/README.md

@@ -16,7 +16,7 @@ and run the following command on Windows:
 If you can't get the short-form commands to work, try invoking Java directly:
 
     java -cp lib/js.jar org.mozilla.javascript.tools.shell.Main -opt -1 \
-    -modules node_modules -modules rhino_modules -modules . \
+    -modules nodejs_modules -modules rhino_modules -modules . \
     jsdoc.js -T
 
 Writing Tests

test/fixtures/getset.js

@@ -0,0 +1,37 @@
+/** @class */
+var Person = makeClass(
+    /** @lends Person# */
+    {
+        /** Set up initial values. */
+        initialize: function(name) {
+        },
+
+        /** Speak a message. */
+        say: function(message) {
+            return this.name + " says: " + message;
+        },
+
+        /**
+         * The name of the person.
+         * @type {string}
+         */
+        get name() {
+            return this._name;
+        },
+
+        /**
+         * @type {string}
+         * @param val
+         */
+        set name(val) {
+            this._name = name;
+        },
+
+        /**
+         * @type {number}
+         */
+        get age() {
+            return 25;
+        }
+    }
+);

test/spec-collection.js

@@ -36,7 +36,7 @@ exports.load = function(loadpath, matcher, clear) {
         var file = path.join(env.dirname, loadpath, wannaBeSpecs[i]);
         try {
             if (fs.statSync(file).isFile()) {
-                if (!/.*node_modules.*/.test(file) && matcher.test(path.filename(file))) {
+                if (!/.*nodejs_modules.*/.test(file) && matcher.test(path.filename(file))) {
                     specs.push(createSpecObj(file));
                 }
             }

test/specs/documentation/getset.js

@@ -0,0 +1,23 @@
+describe("When a getter or setter is the child of an object literal", function () {
+    var docSet = jasmine.getDocSetFromFile("test/fixtures/getset.js"),
+        foundName = docSet.getByLongname("Person#name"),
+        foundAge = docSet.getByLongname("Person#age");
+
+    it("should have a doclet with the correct longname", function () {
+        expect(foundName.length).toEqual(2);
+        expect(foundAge.length).toEqual(1);
+    });
+
+    it("should have a doclet with the correct name", function () {
+        expect(foundName[0].name).toEqual("name");
+        expect(foundName[1].name).toEqual("name");
+        expect(foundAge[0].name).toEqual("age");
+    });
+
+    it("should have the correct memberof", function () {
+        expect(foundName[0].memberof).toEqual("Person");
+        expect(foundName[1].memberof).toEqual("Person");
+        expect(foundAge[0].memberof).toEqual("Person");
+    });
+
+});