Merge pull request #588 from brettz9/jsdoc

Jsdoc

lib/npm-check-updates.js

@@ -305,8 +305,14 @@ function initOptions(options) {
     });
 }
 
+/**
+* @typedef {Array} PkgInfo
+* @property 0 pkgFile
+* @property 1 pkgData
+*/
+
 /** Finds the package file and data.
-    @returns Promise [pkgFile, pkgData]
+    @returns Promise<PkgInfo>
 
 Searches as follows:
  --packageData flag

lib/package-managers/bower.js

@@ -4,6 +4,7 @@ const chalk = require('chalk');
 const requireg = require('requireg');
 
 /**
+ * @param args
  * @param args.global
  * @param args.registry
  * @param args.loglevel
@@ -24,6 +25,12 @@ const bower = ({loglevel}) => {
 
 module.exports = {
 
+    /**
+     * @param {Object} [info]
+     * @param {string} info.prefix
+     * @param {string} info.loglevel
+     * @returns {Promise<Object>}
+     */
     list({prefix, loglevel} = {}) {
 
         return new Promise((resolve, reject) => {
@@ -37,6 +44,14 @@ module.exports = {
         });
     },
 
+    /**
+     * @param {string} packageName
+     * @param _
+     * @param {Object} [info]
+     * @param {string} info.prefix
+     * @param {string} info.loglevel
+     * @returns {Promise}
+     */
     latest(packageName, _, {prefix, loglevel} = {}) {
 
         return new Promise((resolve, reject) => {
@@ -51,6 +66,14 @@ module.exports = {
         });
     },
 
+    /**
+     * @param {string} packageName
+     * @param _
+     * @param {Object} [info]
+     * @param {string} info.prefix
+     * @param {string} info.loglevel
+     * @returns {Promise}
+     */
     greatest(packageName, _, {prefix, loglevel} = {}) {
 
         return new Promise((resolve, reject) => {

lib/package-managers/npm.js

@@ -19,9 +19,17 @@ require('libnpmconfig').read().forEach((value, key) => {
 });
 npmConfig.cache = false;
 
-/** Parse JSON and throw an informative error on failure.
+/**
+* @typedef {Object} CommandAndPackageName
+* @property {string} command
+* @property {string} packageName
+*/
+
+/**
+ * Parse JSON and throw an informative error on failure.
  * @param result Data to be parsed
- * @param data { command, packageName }
+ * @param {CommandAndPackageName} data
+ * @returns {Object}
 */
 function parseJson(result, data) {
     let json;
@@ -35,9 +43,10 @@ function parseJson(result, data) {
 }
 
 /**
- * @param packageName   Name of the package
- * @param field         Field such as "versions" or "dist-tags.latest" are parsed from the pacote result (https://www.npmjs.com/package/pacote#packument)
- * @Returns             Promised result
+ * @param {string} packageName   Name of the package
+ * @param {string} field         Field such as "versions" or "dist-tags.latest" are parsed from the pacote result (https://www.npmjs.com/package/pacote#packument)
+ * @param {string} currentVersion
+ * @returns {Promise}             Promised result
  */
 function view(packageName, field, currentVersion) {
     if (currentVersion && (!semver.validRange(currentVersion) || versionUtil.isWildCard(currentVersion))) {
@@ -61,23 +70,29 @@ function view(packageName, field, currentVersion) {
 }
 
 /**
- * @param versions  Array of all available versions
- * @Returns         An array of versions with the release versions filtered out
+ * @param {Array} versions  Array of all available versions
+ * @returns {Array}         An array of versions with the release versions filtered out
  */
 function filterOutPrereleaseVersions(versions) {
     return _.filter(versions, _.negate(isPre));
 }
 
 /**
  * @param            version
- * @Returns          True if the version is any kind of prerelease: alpha, beta, rc, pre
+ * @returns {boolean}          True if the version is any kind of prerelease: alpha, beta, rc, pre
  */
 function isPre(version) {
     return versionUtil.getPrecision(version) === 'release';
 }
 
 
-/** Spawn npm requires a different command on Windows. */
+/**
+ * Spawn npm requires a different command on Windows.
+ * @param args
+ * @param {Object} [npmOptions={}]
+ * @param {Object} [spawnOptions={}]
+ * @returns {Promise<string>}
+ */
 function spawnNpm(args, npmOptions={}, spawnOptions={}) {
     const cmd = process.platform === 'win32'? 'npm.cmd' : 'npm';
 
@@ -92,12 +107,14 @@ function spawnNpm(args, npmOptions={}, spawnOptions={}) {
 }
 
 /** Get platform-specific default prefix to pass on to npm.
- * @param options.global
- * @param options.prefix
+ * @param {Object} options
+ * @param {boolean} [options.global]
+ * @param [options.prefix]
+ * @returns {Promise<string>}
 */
 function defaultPrefix(options) {
 
-    if (options && options.prefix) {
+    if (options.prefix) {
         return Promise.resolve(options.prefix);
     }
 
@@ -119,9 +136,11 @@ function defaultPrefix(options) {
 module.exports = {
 
     /**
-     * @options.cwd (optional)
-     * @options.global (optional)
-     * @options.prefix (optional)
+     * @param [options]
+     * @param [options.cwd]
+     * @param [options.global]
+     * @param [options.prefix]
+     * @returns {Promise<Object>}
     */
     list(options={}) {
 
@@ -137,6 +156,12 @@ module.exports = {
             });
     },
 
+    /**
+     * @param {string} packageName
+     * @param {string} currentVersion
+     * @param {boolean} pre
+     * @returns {Promise}
+     */
     latest(packageName, currentVersion, pre) {
         return view(packageName, 'dist-tags.latest', currentVersion)
             .then(version => {
@@ -154,6 +179,12 @@ module.exports = {
             });
     },
 
+    /**
+     * @param {string} packageName
+     * @param {string} currentVersion
+     * @param {boolean} pre
+     * @returns {Promise}
+     */
     newest(packageName, currentVersion, pre) {
         return view(packageName, 'time', currentVersion)
             .then(_.keys)
@@ -163,20 +194,38 @@ module.exports = {
             });
     },
 
+    /**
+     * @param {string} packageName
+     * @param {string} currentVersion
+     * @param {boolean} pre
+     * @returns {Promise}
+     */
     greatest(packageName, currentVersion, pre) {
         return view(packageName, 'versions', currentVersion)
             .then(versions => {
                 return _.last(pre ? versions : filterOutPrereleaseVersions(versions));
             });
     },
 
+    /**
+     * @param {string} packageName
+     * @param {string} currentVersion
+     * @param {boolean} pre
+     * @returns {Promise}
+     */
     greatestMajor(packageName, currentVersion, pre) {
         return view(packageName, 'versions', currentVersion).then(versions => {
             const resultVersions = pre ? versions : filterOutPrereleaseVersions(versions);
             return versionUtil.findGreatestByLevel(resultVersions, currentVersion, 'major');
         });
     },
 
+    /**
+     * @param {string} packageName
+     * @param {string} currentVersion
+     * @param {boolean} pre
+     * @returns {Promise}
+     */
     greatestMinor(packageName, currentVersion, pre) {
         return view(packageName, 'versions', currentVersion).then(versions => {
             const resultVersions = pre ? versions : filterOutPrereleaseVersions(versions);

lib/raw-promisify.js

@@ -4,6 +4,8 @@
  * For some reason, Promise.promisifyAll does not work on npm.commands :(
  *   Promise.promisifyAll(npm.commands);
  * So we have to do it manually.
+ * @param {Object} obj
+ * @returns {void}
  */
 function rawPromisify(obj) {
     Object.entries(obj).forEach(([name, method]) => {

lib/version-util.js

@@ -22,7 +22,8 @@ const WILDCARD_PURE_REGEX = new RegExp(`^(${WILDCARDS_PURE.join('|')
 const SEMANTIC_DIRECT = new RegExp('^\\d+\\.\\d+\\.\\d+([-|+].*)*$');
 
 /**
- * Returns the number of parts in the version
+ * @param {string} version
+ * @returns {number} The number of parts in the version
  */
 function numParts(version) {
 
@@ -37,6 +38,9 @@ function numParts(version) {
 
 /**
  * Increases or decreases the given precision by the given amount, e.g. major+1 -> minor
+ * @param {string} precision
+ * @param {number} n
+ * @returns {string}
  */
 function precisionAdd(precision, n) {
 
@@ -51,15 +55,21 @@ function precisionAdd(precision, n) {
 
     if (index === null) {
         throw new Error(`Invalid precision: ${precision}`);
-    } else if (!VERSION_PARTS[index]) {
+    }
+    if (!VERSION_PARTS[index]) {
         throw new Error(`Invalid precision math${arguments}`);
     }
 
     return VERSION_PARTS[index];
 }
 
-/** Joins the major, minor, patch, release, and build parts (controlled by an optional precision arg) of a semver object
- * into a dot-delimited string. */
+/**
+ * Joins the major, minor, patch, release, and build parts (controlled by an
+ * optional precision arg) of a semver object into a dot-delimited string.
+ * @param semver
+ * @param {string} [precision]
+ * @returns {string}
+ */
 function stringify(semver, precision) {
 
     // get a list of the parts up until (and including) the given precision
@@ -79,6 +89,8 @@ function stringify(semver, precision) {
 
 /**
  * Gets how precise this version number is (major, minor, patch, release, or build)
+ * @param {string} version
+ * @returns {string}
  */
 function getPrecision(version) {
     const [semver] = semverutils.parseRange(version);
@@ -88,32 +100,52 @@ function getPrecision(version) {
 
 /**
  * Sets the precision of a (loose) semver to the specified level: major, minor, etc.
+ * @param {string} version
+ * @param {string} [precision]
+ * @returns {string}
  */
 function setPrecision(version, precision) {
     const [semver] = semverutils.parseRange(version);
     return stringify(semver, precision);
 }
 
-/** Adds a given wildcard (^,~,.*,.x) to a version number. Adds ^ and ~ to the beginning. Replaces everything after the
- * major version number with .* or .x */
+/**
+ * Adds a given wildcard (^,~,.*,.x) to a version number. Adds ^ and ~ to the
+ * beginning. Replaces everything after the major version number with .* or .x
+ * @param {string} version
+ * @param {string} wildcard
+ * @returns {string}
+ */
 function addWildCard(version, wildcard) {
     return wildcard === '^' || wildcard === '~' ?
         wildcard + version :
         setPrecision(version, 'major') + wildcard;
 }
 
-/** Returns true if the given string is one of the wild cards. */
+/**
+ * Returns true if the given string is one of the wild cards.
+ * @param {string} version
+ * @returns {boolean}
+ */
 function isWildCard(version) {
     return WILDCARD_PURE_REGEX.test(version);
 }
 
-/** Returns true if the given digit is a wildcard for a part of a version. */
+/**
+ * Returns true if the given digit is a wildcard for a part of a version.
+ * @param {"*"|"x"} versionPart
+ * @returns {boolean}
+ */
 function isWildPart(versionPart) {
     return versionPart === '*' || versionPart === 'x';
 }
 
 /**
- * Colorize the parts of a version string (to) that are different than another (from). Assumes that the two verson strings are in the same format.
+ * Colorize the parts of a version string (to) that are different than
+ * another (from). Assumes that the two verson strings are in the same format.
+ * @param from
+ * @param to
+ * @returns {string}
  */
 function colorizeDiff(from, to) {
     let leadingWildcard = '';
@@ -152,7 +184,7 @@ function colorizeDiff(from, to) {
  * @param versions  Array of all available versions
  * @param current   Current version
  * @param level     major/minor
- * @Returns         String representation of the suggested version. If the current version
+ * @returns {string}         String representation of the suggested version. If the current version
  * is not direct then returns null
  */
 function findGreatestByLevel(versions, current, level) {