jsdoc - npm Package Compare versions

Comparing version 3.3.0-alpha8 to 3.3.0-alpha9

jsdoc.js

@@ -101,3 +101,6 @@ #!/usr/bin/env node
         require = require('requizzle')({
-            requirePaths: [path.join(__dirname, 'lib'), path.join(__dirname, 'node_modules')],
+            requirePaths: {
+                before: [path.join(__dirname, 'lib')],
+                after: [path.join(__dirname, 'node_modules')]
+            },
             infect: true
@@ -104,0 +107,0 @@ });

lib/jsdoc/doclet.js

@@ -397,4 +397,9 @@ /**
         }
+        // the AST node is only enumerable in debug mode, which reduces clutter for the
+        // --explain/-X option
         if (meta.code.node) {
-            this.meta.code.node = meta.code.node;
+            Object.defineProperty(this.meta.code, 'node', {
+                value: meta.code.node,
+                enumerable: global.env.opts.debug ? true : false
+            });
         }
@@ -401,0 +406,0 @@ if (meta.code.funcscope) {

lib/jsdoc/src/astnode.js

@@ -261,3 +261,4 @@ // TODO: docs
     switch (node.type) {
-        // like: "foo = 'bar'" (after foo has been declared)
+        // like: "foo = 'bar'" (after declaring foo)
+        // like: "MyClass.prototype.myMethod = function() {}" (after declaring MyClass)
         case Syntax.AssignmentExpression:
@@ -268,2 +269,4 @@ info.node = node.right;
             info.value = nodeToString(info.node);
+            // if the assigned value is a function, we need to capture the parameter names here
+            info.paramnames = getParamNames(node.right);
             break;
@@ -270,0 +273,0 @@

lib/jsdoc/src/handlers.js

@@ -89,4 +89,16 @@ /**
 
-        // an undocumented symbol right after a virtual comment? rhino mistakenly connected the two
-        if (newDoclet.name) { // there was a @name in comment
+        // A JSDoc comment can define a symbol name by including:
+        //
+        // + A `@name` tag
+        // + Another tag that accepts a name, such as `@function`
+        //
+        // When the JSDoc comment defines a symbol name, we treat it as a "virtual comment" for a
+        // symbol that isn't actually present in the code. And if a virtual comment is attached to
+        // a symbol, it's quite possible that the comment and symbol have nothing to do with one
+        // another.
+        //
+        // As a result, if we create a doclet for a `symbolFound` event, and we've already added a
+        // name attribute by parsing the JSDoc comment, we need to create a new doclet that ignores
+        // the attached JSDoc comment and only looks at the code.
+        if (newDoclet.name) {
             // try again, without the comment
@@ -93,0 +105,0 @@ e.comment = '@undocumented';

lib/jsdoc/tag.js

@@ -126,3 +126,2 @@ /*global env: true */
             processTagText(this, tagDef);
-            jsdoc.tag.validator.validate(this, tagDef, meta);
         }
@@ -140,2 +139,4 @@ catch (e) {
     }
+
+    jsdoc.tag.validator.validate(this, tagDef, meta);
 };

lib/jsdoc/tag/dictionary/definitions.js

@@ -11,2 +11,3 @@ /*global app, env */
 
+var hasOwnProp = Object.prototype.hasOwnProperty;
 var jsdoc = {
@@ -100,5 +101,8 @@ name: require('jsdoc/name'),
     if (tag.value && tag.value.type) {
-        // add the type names and other type properties (such as `optional`)
+        // Add the type names and other type properties (such as `optional`).
+        // Don't overwrite existing properties.
         Object.keys(tag.value).forEach(function(prop) {
-            doclet[prop] = tag.value[prop];
+            if ( !hasOwnProp.call(doclet, prop) ) {
+                doclet[prop] = tag.value[prop];
+            }
         });
@@ -385,13 +389,2 @@ }
 
-    dictionary.defineTag('exception', {
-        mustHaveValue: true,
-        canHaveType: true,
-        onTagged: function(doclet, tag) {
-            if (!doclet.exceptions) { doclet.exceptions = []; }
-            doclet.exceptions.push(tag.value);
-            setDocletTypeToValueType(doclet, tag);
-        }
-    })
-    .synonym('throws');
-
     dictionary.defineTag('exports', {
@@ -704,2 +697,13 @@ mustHaveValue: true,
 
+    dictionary.defineTag('throws', {
+        mustHaveValue: true,
+        canHaveType: true,
+        onTagged: function(doclet, tag) {
+            if (!doclet.exceptions) { doclet.exceptions = []; }
+            doclet.exceptions.push(tag.value);
+            setDocletTypeToValueType(doclet, tag);
+        }
+    })
+    .synonym('exception');
+
     dictionary.defineTag('tutorial', {
@@ -706,0 +710,0 @@ mustHaveValue: true,

lib/jsdoc/util/markdown.js

@@ -1,2 +0,2 @@
-/*global env: true */
+/*global env */
 
@@ -11,2 +11,4 @@ /**
 
+var util = require('util');
+
 /**
@@ -69,2 +71,14 @@ * Enumeration of Markdown parsers that are available.
 /**
+ * Escape characters in text within a code block.
+ *
+ * @param {string} source - The source text to escape.
+ * @return {string} The escaped source text.
+ */
+function escapeCode(source) {
+    return source.replace(/</g, '&lt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+
+/**
  * Retrieve a function that accepts a single parameter containing Markdown source. The function uses
@@ -91,10 +105,13 @@ * the specified parser to transform the Markdown source to HTML, then returns the HTML as a string.
         markedRenderer = new marked.Renderer();
+
         markedRenderer.heading = function(text, level) {
-            var util = require('util');
-
             return util.format('<h%s>%s</h%s>', level, text, level);
         };
+
         // Allow prettyprint to work on inline code samples
         markedRenderer.code = function(code, language) {
-          return '<pre class="prettyprint source"><code>' + code + '</code></pre>';
+            var langClass = language ? ' lang-' + language : '';
+
+            return util.format( '<pre class="prettyprint source%s"><code>%s</code></pre>',
+                langClass, escapeCode(code) );
         };
@@ -101,0 +118,0 @@

lib/jsdoc/util/templateHelper.js

@@ -144,2 +144,7 @@ /*global env: true */
 
+function isComplexTypeExpression(expr) {
+    // record types, type unions, and type applications all count as "complex"
+    return expr.search(/[{(|]/) !== -1 || expr.search(/</) > 0;
+}
+
 /**
@@ -189,3 +194,3 @@ * Build an HTML link to the symbol with the specified longname. If the longname is not
     // (but skip anything that looks like an inline tag)
-    else if (longname && longname.search(/[<{(]/) !== -1 && /\{\@.+\}/.test(longname) === false) {
+    else if (longname && isComplexTypeExpression(longname) && /\{\@.+\}/.test(longname) === false) {
         parsedType = parseType(longname);
@@ -440,3 +445,3 @@ return stringifyType(parsedType, options.cssClass, options.linkMap);
 /**
- * Check whether a symbol is a function and is the only symbol exported by a module (as in
+ * Check whether a symbol is the only symbol exported by a module (as in
  * `module.exports = function() {};`).
@@ -446,10 +451,10 @@ *
  * @param {module:jsdoc/doclet.Doclet} doclet - The doclet for the symbol.
- * @return {boolean} `true` if the symbol is a function and is the only symbol exported by a module;
- * otherwise, `false`.
+ * @return {boolean} `true` if the symbol is the only symbol exported by a module; otherwise,
+ * `false`.
  */
-function isModuleFunction(doclet) {
+function isModuleExports(doclet) {
     var MODULE_PREFIX = require('jsdoc/name').MODULE_PREFIX;
 
     return doclet.longname && doclet.longname === doclet.name &&
-        doclet.longname.indexOf(MODULE_PREFIX) === 0 && doclet.kind === 'function';
+        doclet.longname.indexOf(MODULE_PREFIX) === 0 && doclet.kind !== 'module';
 }
@@ -487,3 +492,3 @@
     members.globals = members.globals.filter(function(doclet) {
-        return !isModuleFunction(doclet);
+        return !isModuleExports(doclet);
     });
@@ -745,3 +750,3 @@
     // the doclet gets its own HTML file
-    if ( containers.indexOf(doclet.kind) !== -1 || isModuleFunction(doclet) ) {
+    if ( containers.indexOf(doclet.kind) !== -1 || isModuleExports(doclet) ) {
         filename = getFilename(longname);
@@ -748,0 +753,0 @@ }

package.json

 {
   "name": "jsdoc",
-  "version": "3.3.0-alpha8",
-  "revision": "1402517102726",
+  "version": "3.3.0-alpha9",
+  "revision": "1403969163513",
   "description": "An API documentation generator for JavaScript.",
@@ -26,3 +26,3 @@ "keywords": [
     "marked": "~0.3.1",
-    "requizzle": "~0.1.1",
+    "requizzle": "~0.2.0",
     "strip-json-comments": "~0.1.3",
@@ -29,0 +29,0 @@ "taffydb": "https://github.com/hegemonic/taffydb/tarball/master",

README.md

@@ -118,6 +118,8 @@ JSDoc 3
 
-Project Documentation: <http://usejsdoc.org/>  
-Project Documentation Source: <https://github.com/jsdoc3/jsdoc3.github.com>  
-JSDoc User's Group: <http://groups.google.com/group/jsdoc-users>  
-Project Announcements: <http://twitter.com/jsdoc3>
++ Documentation is available at [Use JSDoc](http://usejsdoc.org).
++ Contribute to the docs at [jsdoc3/jsdoc3.github.com](https://github.com/jsdoc3/jsdoc3.github.com).
++ ~~Post questions to the [JSDoc Users mailing list](http://groups.google.com/group/jsdoc-users).~~
+(temporarily unavailable)
++ Post questions tagged `jsdoc` to [Stack
+Overflow](http://stackoverflow.com/questions/tagged/jsdoc).
 
@@ -124,0 +126,0 @@ License

templates/default/publish.js

@@ -99,3 +99,5 @@ /*global env: true */
 function addParamAttributes(params) {
-    return params.map(updateItemName);
+    return params.filter(function(param) {
+        return param.name && param.name.indexOf('.') === -1;
+    }).map(updateItemName);
 }
@@ -102,0 +104,0 @@

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

435444

increased by0.87%

Number of package files

97

increased by1.04%

Lines of code

9808

increased by0.47%

Number of lines in readme file

133

increased by1.53%

Dependency changes

• + Addedrequizzle@0.2.4(transitive)

• - Removedrequizzle@0.1.1(transitive)

• Updatedrequizzle@~0.2.0