jsdoc - npm Package Compare versions

Comparing version 3.5.1 to 3.5.2

CHANGES.md

 # JSDoc 3 change history
 
-This file describes notable changes in each version of JSDoc 3. To download a specific version of
-JSDoc 3, see [GitHub's tags page](https://github.com/jsdoc3/jsdoc/tags).
+This file describes notable changes in each version of JSDoc 3.
 
 
+## 3.5.2 (July 2017)
+
++ The default template now hides parameters and properties for class constructors that are hidden
+with the `@hideconstructor` tag. (#1397)
++ Non-JSDoc comments (comments that do not begin with `/**`) are now ignored. (#1398)
++ JSDoc now uses an improved algorithm for locating plugins and template resources. (#1394)
++ When the `@alias` tag identifies an instance member (for example, `@alias Foo#bar`), the alias is
+now applied correctly. (#1385)
++ When the `@alias` tag is applied to a class that is within a module and is aliased to the module
+name, the class's instance members are now documented correctly. (#1134)
++ Fixed a crash when a `@param` tag uses the wrong delimiter to close the type expression (for
+example, `@param {Object)`). (#1221)
++ The Markdown plugin now converts Markdown-formatted text in the `@summary` tag. (#1149)
+
+
 ## 3.5.1 (July 2017)
@@ -8,0 +22,0 @@

cli.js

@@ -331,11 +331,2 @@ /* eslint indent: "off", no-process-exit: "off", strict: ["error", "function"] */
         var dirname = path.dirname(plugin);
-
-        // support plugin specification as an installed package, which
-        // then may not have a directory component, resulting in
-        // path.dirname() to return '.', which, if passed on, would
-        // result in different path resolution semantics
-        if (dirname.indexOf('.') === 0 && plugin.indexOf('.') !== 0) {
-            dirname = undefined;
-        }
-
         var pluginPath = path.getResourcePath(dirname, basename);
@@ -342,0 +333,0 @@

lib/jsdoc/name.js

@@ -104,4 +104,12 @@ /**
 
+    // does the doclet have an alias that identifies the memberof? if so, use it
+    if (doclet.alias) {
+        about = exports.shorten(name);
+
+        if (about.memberof) {
+            memberof = about.memberof;
+        }
+    }
     // member of a var in an outer scope?
-    if (name && !memberof && doclet.meta.code && doclet.meta.code.funcscope) {
+    else if (name && !memberof && doclet.meta.code && doclet.meta.code.funcscope) {
         name = doclet.longname = doclet.meta.code.funcscope + SCOPE.PUNC.INNER + name;
@@ -108,0 +116,0 @@ }

lib/jsdoc/path.js

@@ -88,32 +88,33 @@ /**
  *
- * Plugins and templates will be found somewhat similar to how
- * require() works, except that the directory in which the JSDoc
- * configuration file is will be considered, too, the JSDoc package
- * directory will be considered as a fallback, and a globally
- * installed resource won't be found unless it comes with JSDoc.
+ * If the resource path is specified as a relative path, JSDoc searches for the resource in the
+ * following locations, in this order:
  *
- * If the resource path is specified as a path relative to module or
- * package (starting with "`.`" or "`..`") JSDoc searches for the path
- * first in the current working directory, then where the JSDoc
- * configuration file is located, and finally as a fall-back under the
- * JSDoc directory. Otherwise, if the resource path is relative (not
- * starting with a path separator), JSDoc searches first under the
- * `node_modules` directory in the current working directory and where
- * the JSDoc configuration file is located, and then where JSDoc is
- * installed.
+ * 1. The current working directory
+ * 2. The directory where the JSDOc configuration file is located
+ * 3. The JSDoc directory
+ * 4. Anyplace where `require()` can find the resource (for example, in your project's
+ * `node_modules` directory)
  *
- * If the resource path is specified as a fully qualified path, JSDoc uses the path as-is.
+ * If the resource path is specified as a fully qualified path, JSDoc searches for the resource in
+ * the following locations, in this order:
  *
+ * 1. The resource path
+ * 2. Anyplace where `require()` can find the resource (for example, in your project's
+ * `node_modules` directory)
+ *
  * @param {string} filepath - The path to the requested resource. May be an absolute path; a path
  * relative to the JSDoc directory; or a path relative to the current working directory.
  * @param {string} [filename] - The filename of the requested resource.
- * @return {string} The fully qualified path to the requested resource.
- * Includes the filename if one was provided.
+ * @return {string} The fully qualified path to the requested resource. Includes the filename if one
+ * was provided.
  */
 exports.getResourcePath = function(filepath, filename) {
     var result = null;
+    var searchDirs = [env.pwd, path.dirname(env.opts.configure || ''), env.dirname];
 
-    function pathExists(_path) {
+    function exists(p) {
         try {
-            fs.readdirSync(_path);
+            fs.statSync(p);
+
+            return true;
         }
@@ -123,47 +124,46 @@ catch (e) {
         }
+    }
 
-        return true;
+    function resolve(p) {
+        try {
+            return require.resolve(p);
+        }
+        catch (e) {
+            return null;
+        }
     }
 
-    var searchDirs = [];
+    function find(p) {
+        // does the requested path exist?
+        if ( exists(p) ) {
+            result = p;
+        }
+        else {
+            // can `require()` find the requested path?
+            result = resolve(p);
+        }
 
-    // resources that are installed modules may not have been
-    // specified with a filepath
-    if (!filepath) {
-        filepath = filename;
-        filename = undefined;
+        return Boolean(result);
     }
-    var pathElems = filepath.split(path.sep);
 
-    // Special case 'node_modules/foo', to accommodate this legacy
-    // workaround advertised by 3rd party plugin and template authors
-    if (pathElems[0] === 'node_modules') {
-        pathElems.unshift('.');
-        filepath = pathElems.join(path.sep);
+    filepath = path.join(filepath, filename || '');
+
+    // is the filepath absolute? if so, just use it
+    if ( path.isAbsolute(filepath) ) {
+        find(filepath);
     }
-
-    // search in different sets of directories depending on whether
-    // filepath is expressly relative to "current" directory or not
-    searchDirs = pathElems[0].indexOf('.') === 0 ?
-        // look first in "current" (where jsdoc was executed), then in
-        // directory of config, and _only then_ in jsdoc's directory
-        [env.pwd, path.dirname(env.opts.configure || ''), env.dirname] :
-        // otherwise, treat as relative to where plugins/templates are
-        // found, either as a dependency, or under jsdoc itself
-        [path.join(env.pwd, 'node_modules'),
-            path.join(path.dirname(env.opts.configure || ''), 'node_modules'),
-            env.dirname];
-
-    // absolute paths are normalized by path.resolve on the first pass
-    searchDirs.forEach(function(_path) {
-        if (!result && _path) {
-            _path = path.resolve(_path, filepath);
-            if ( pathExists(_path) ) {
-                result = _path;
+    else {
+        searchDirs.some(function(searchDir) {
+            if (searchDir) {
+                return find( path.resolve(path.join(searchDir, filepath)) );
             }
-        }
-    });
+            else {
+                return false;
+            }
+        });
+    }
 
-    if (result) {
-        result = filename ? path.join(result, filename) : result;
+    // if we still haven't found the resource, maybe it's an installed module
+    if (!result) {
+        result = resolve(filepath);
     }
@@ -170,0 +170,0 @@

lib/jsdoc/src/parser.js

@@ -464,6 +464,13 @@ /**
 
-    // In general, if there's an enclosing scope, we use the enclosing scope to resolve `this`.
-    // For object properties, we use the node's parent (the object) instead.
+    // Properties are handled below.
     if (node.type !== Syntax.Property && node.enclosingScope) {
-        doclet = this._getDocletById(node.enclosingScope.nodeId);
+        // For ES2015 constructor functions, we use the class declaration to resolve `this`.
+        if (node.parent && node.parent.type === Syntax.MethodDefinition &&
+            node.parent.kind === 'constructor') {
+            doclet = this._getDocletById(node.parent.parent.parent.nodeId);
+        }
+        // Otherwise, if there's an enclosing scope, we use the enclosing scope to resolve `this`.
+        else {
+            doclet = this._getDocletById(node.enclosingScope.nodeId);
+        }
 
@@ -503,2 +510,3 @@ if (!doclet) {
     }
+    // For object properties, we use the node's parent (the object) instead.
     else {
@@ -505,0 +513,0 @@ doclet = this._getDocletById(node.parent.nodeId);

lib/jsdoc/src/visitor.js

@@ -475,4 +475,4 @@ /**
 /**
- * Verify that a block comment exists and that its leading delimiter does not contain three or more
- * asterisks.
+ * Verify that a block comment exists; that it is a JSDoc comment; and that its leading delimiter
+ * does not contain three or more asterisks.
  *
@@ -483,7 +483,8 @@ * @private
 function isValidJsdoc(commentSrc) {
-    return commentSrc && commentSrc.indexOf('/***') !== 0;
+    return commentSrc && commentSrc.indexOf('/**') === 0 &&
+        commentSrc.indexOf('/***') !== 0;
 }
 
 // TODO: docs
-function hasJsdocComments(node) {
+function hasComments(node) {
     return (node && node.leadingComments && node.leadingComments.length) ||
@@ -512,3 +513,3 @@ (node && node.trailingComments && node.trailingComments.length) ||
 
-    if ( !hasJsdocComments(node) && (!node.type || !isBlock) ) {
+    if ( !hasComments(node) && (!node.type || !isBlock) ) {
         return true;
@@ -567,3 +568,3 @@ }
 
-    if (!e.preventDefault && e.comment && isValidJsdoc(e.comment)) {
+    if (!e.preventDefault) {
         parser.emit(e.event, e, parser);
@@ -570,0 +571,0 @@ }

package.json

 {
   "name": "jsdoc",
-  "version": "3.5.1",
-  "revision": "1499710618011",
+  "version": "3.5.2",
+  "revision": "1499883458597",
   "description": "An API documentation generator for JavaScript.",
@@ -6,0 +6,0 @@ "keywords": [

plugins/markdown.js

@@ -19,3 +19,4 @@ /**
     'returns',
-    'see'
+    'see',
+    'summary'
 ];
@@ -22,0 +23,0 @@ var hasOwnProp = Object.prototype.hasOwnProperty;

plugins/test/fixtures/markdown.js

@@ -22,2 +22,3 @@ 'use strict';
  * @see [Example Inc.](http://example.com)
+ * @summary My class.
  */
@@ -24,0 +25,0 @@ function MyClass(myParam) {

plugins/test/specs/markdown.js

@@ -27,3 +27,4 @@ 'use strict';
             myClass.returns[0].description,
-            myClass.see
+            myClass.see,
+            myClass.summary
         ].forEach(function(value) {
@@ -30,0 +31,0 @@ // if we processed the value, it should be wrapped in a <p> tag

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

Dynamic require

Supply chain risk

Dynamic require can indicate the package is performing dangerous or unsafe dynamic code execution.

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

1524875

increased by0.03%

Lines of code

12531

increased by0.1%

Worsened metrics

Number of low supply chain risk alerts

16

increased by6.67%

No dependency changes