Add eslint jsdoc support.

- Add eslint jsdoc support.
- Fix lint issues.

.eslintrc.js

@@ -6,8 +6,12 @@ module.exports = {
     node: true
   },
   extends: [
-    'digitalbazaar'
+    'digitalbazaar',
+    'digitalbazaar/jsdoc'
   ],
+  rules: {
+    'jsdoc/require-description-complete-sentence': 'off'
+  },
   ignorePatterns: [
     'test-suites'
   ]

lib/IdentifierIssuer.js

@@ -8,9 +8,9 @@ module.exports = class IdentifierIssuer {
    * Creates a new IdentifierIssuer. A IdentifierIssuer issues unique
    * identifiers, keeping track of any previously issued identifiers.
    *
-   * @param prefix the prefix to use ('<prefix><counter>').
-   * @param existing an existing Map to use.
-   * @param counter the counter to use.
+   * @param {string} prefix - The prefix to use ('<prefix><counter>').
+   * @param {Map} [existing] - An existing Map to use.
+   * @param {number} [counter] - The counter to use.
    */
   constructor(prefix, existing = new Map(), counter = 0) {
     this.prefix = prefix;
@@ -21,7 +21,7 @@ module.exports = class IdentifierIssuer {
   /**
    * Copies this IdentifierIssuer.
    *
-   * @return a copy of this IdentifierIssuer.
+   * @returns {object} - A copy of this IdentifierIssuer.
    */
   clone() {
     const {prefix, _existing, counter} = this;
@@ -32,9 +32,9 @@ module.exports = class IdentifierIssuer {
    * Gets the new identifier for the given old identifier, where if no old
    * identifier is given a new identifier will be generated.
    *
-   * @param [old] the old identifier to get the new identifier for.
+   * @param {string} [old] - The old identifier to get the new identifier for.
    *
-   * @return the new identifier.
+   * @returns {string} - The new identifier.
    */
   getId(old) {
     // return existing old identifier
@@ -59,10 +59,10 @@ module.exports = class IdentifierIssuer {
    * Returns true if the given old identifer has already been assigned a new
    * identifier.
    *
-   * @param old the old identifier to check.
+   * @param {string} old - The old identifier to check.
    *
-   * @return true if the old identifier has been assigned a new identifier,
-   *   false if not.
+   * @returns {boolean} - True if the old identifier has been assigned a new
+   *   identifier, false if not.
    */
   hasId(old) {
     return this._existing.has(old);
@@ -72,7 +72,8 @@ module.exports = class IdentifierIssuer {
    * Returns all of the IDs that have been issued new IDs in the order in
    * which they were issued new IDs.
    *
-   * @return the list of old IDs that has been issued new IDs in order.
+   * @returns {Array} - The list of old IDs that has been issued new IDs in
+   *   order.
    */
   getOldIds() {
     return [...this._existing.keys()];

lib/MessageDigest-webcrypto.js

@@ -9,7 +9,7 @@ module.exports = class MessageDigest {
   /**
    * Creates a new WebCrypto API MessageDigest.
    *
-   * @param algorithm the algorithm to use.
+   * @param {string} algorithm - The algorithm to use.
    */
   constructor(algorithm) {
     // check if crypto.subtle is available

lib/MessageDigest.js

@@ -9,7 +9,7 @@ module.exports = class MessageDigest {
   /**
    * Creates a new MessageDigest.
    *
-   * @param algorithm the algorithm to use.
+   * @param {string} algorithm - The algorithm to use.
    */
   constructor(algorithm) {
     this.md = crypto.createHash(algorithm);

lib/NQuads.js

@@ -76,9 +76,10 @@ module.exports = class NQuads {
   /**
    * Parses RDF in the form of N-Quads.
    *
-   * @param input the N-Quads input to parse.
+   * @param {string} input - The N-Quads input to parse.
    *
-   * @return an RDF dataset (an array of quads per http://rdf.js.org/).
+   * @returns {Array} - An RDF dataset (an array of quads per
+   *   http://rdf.js.org/).
    */
   static parse(input) {
     // build RDF dataset
@@ -184,9 +185,10 @@ module.exports = class NQuads {
   /**
    * Converts an RDF dataset to N-Quads.
    *
-   * @param dataset (array of quads) the RDF dataset to convert.
+   * @param {Array|object} dataset - (array of quads) the RDF dataset to
+   *   convert.
    *
-   * @return the N-Quads string.
+   * @returns {string} - The N-Quads string.
    */
   static serialize(dataset) {
     if(!Array.isArray(dataset)) {
@@ -202,12 +204,12 @@ module.exports = class NQuads {
   /**
    * Converts RDF quad components to an N-Quad string (a single quad).
    *
-   * @param {Object} s - N-Quad subject component.
-   * @param {Object} p - N-Quad predicate component.
-   * @param {Object} o - N-Quad object component.
-   * @param {Object} g - N-Quad graph component.
+   * @param {object} s - N-Quad subject component.
+   * @param {object} p - N-Quad predicate component.
+   * @param {object} o - N-Quad object component.
+   * @param {object} g - N-Quad graph component.
    *
-   * @return {string} the N-Quad.
+   * @returns {string} - The N-Quad.
    */
   static serializeQuadComponents(s, p, o, g) {
     let nquad = '';
@@ -253,9 +255,9 @@ module.exports = class NQuads {
   /**
    * Converts an RDF quad to an N-Quad string (a single quad).
    *
-   * @param quad the RDF quad convert.
+   * @param {object} quad - The RDF quad convert.
    *
-   * @return the N-Quad string.
+   * @returns {string} - The N-Quad string.
    */
   static serializeQuad(quad) {
     return NQuads.serializeQuadComponents(
@@ -266,9 +268,9 @@ module.exports = class NQuads {
    * Converts a legacy-formatted dataset to an array of quads dataset per
    * http://rdf.js.org/.
    *
-   * @param dataset the legacy dataset to convert.
+   * @param {object} dataset - The legacy dataset to convert.
    *
-   * @return the array of quads dataset.
+   * @returns {Array} - The array of quads dataset.
    */
   static legacyDatasetToQuads(dataset) {
     const quads = [];
@@ -330,10 +332,10 @@ module.exports = class NQuads {
 /**
  * Compares two RDF triples for equality.
  *
- * @param t1 the first triple.
- * @param t2 the second triple.
+ * @param {object} t1 - The first triple.
+ * @param {object} t2 - The second triple.
  *
- * @return true if the triples are the same, false if not.
+ * @returns {boolean} - True if the triples are the same, false if not.
  */
 function _compareTriples(t1, t2) {
   // compare subject and object types first as it is the quickest check
@@ -360,7 +362,11 @@ function _compareTriples(t1, t2) {
 
 const _escapeRegex = /["\\\n\r]/g;
 /**
- * Escape string to N-Quads literal
+ * Escape string to N-Quads literal.
+ *
+ * @param {string} s - String to escape.
+ *
+ * @returns {string} - Escaped N-Quads literal.
  */
 function _escape(s) {
   if(!_escapeRegex.test(s)) {
@@ -379,7 +385,11 @@ function _escape(s) {
 const _unescapeRegex =
   /(?:\\([tbnrf"'\\]))|(?:\\u([0-9A-Fa-f]{4}))|(?:\\U([0-9A-Fa-f]{8}))/g;
 /**
- * Unescape N-Quads literal to string
+ * Unescape N-Quads literal to string.
+ *
+ * @param {string} s - String to unescape.
+ *
+ * @returns {string} - Unescaped N-Quads literal.
  */
 function _unescape(s) {
   if(!_unescapeRegex.test(s)) {

lib/Permuter.js

@@ -8,7 +8,7 @@ module.exports = class Permuter {
    * A Permuter iterates over all possible permutations of the given array
    * of elements.
    *
-   * @param list the array of elements to iterate over.
+   * @param {Array} list - The array of elements to iterate over.
    */
   constructor(list) {
     // original array
@@ -25,7 +25,7 @@ module.exports = class Permuter {
   /**
    * Returns true if there is another permutation.
    *
-   * @return true if there is another permutation, false if not.
+   * @returns {boolean} - True if there is another permutation, false if not.
    */
   hasNext() {
     return !this.done;
@@ -35,7 +35,7 @@ module.exports = class Permuter {
    * Gets the next permutation. Call hasNext() to ensure there is another one
    * first.
    *
-   * @return the next permutation.
+   * @returns {any} - The next permutation.
    */
   next() {
     // copy current permutation to return it

lib/index.js

@@ -66,9 +66,9 @@ exports.IdentifierIssuer = require('./IdentifierIssuer');
 /**
  * Get or set native API.
  *
- * @param api the native API.
+ * @param {object} [api] - The native API.
  *
- * @return the currently set native API.
+ * @returns {object} - The currently set native API.
  */
 exports._rdfCanonizeNative = function(api) {
   if(api) {
@@ -103,7 +103,8 @@ exports._rdfCanonizeNative = function(api) {
  *     meaningless or potentially malicious datasets, a recommended value is
  *     `1`.
  *
- * @return a Promise that resolves to the canonicalized RDF Dataset.
+ * @returns {Promise<object>} - A Promise that resolves to the canonicalized
+ *   RDF Dataset.
  */
 exports.canonize = async function(input, options) {
   const dataset = _inputToDataset(input, options);
@@ -156,7 +157,8 @@ exports.canonize = async function(input, options) {
  *     meaningless or potentially malicious datasets, a recommended value is
  *     `1`.
  *
- * @return the RDF dataset in canonical form.
+ * @returns {Promise<object>} - A Promise that resolves to the canonicalized
+ *   RDF Dataset.
  */
 exports._canonizeSync = function(input, options) {
   const dataset = _inputToDataset(input, options);

package.json

@@ -36,6 +36,7 @@
     "envify": "^4.1.0",
     "eslint": "^8.43.0",
     "eslint-config-digitalbazaar": "^5.0.1",
+    "eslint-plugin-jsdoc": "^46.2.6",
     "esmify": "^2.1.1",
     "fs-extra": "^11.1.1",
     "join-path-js": "^0.0.0",

test/.eslintrc.js

@@ -1,8 +1,5 @@
 module.exports = {
   env: {
     mocha: true
-  },
-  globals: {
-    phantom: true
   }
 };

test/EarlReport.js

@@ -1,5 +1,5 @@
 /**
- * EARL Report
+ * EARL Report.
  *
  * Copyright (c) 2016-2022 Digital Bazaar, Inc. All rights reserved.
  */
@@ -52,14 +52,14 @@ const _benchmarkContext = {
 /* eslint-enable quote-props */
 
 /**
- * EARL Reporter
+ * EARL Reporter.
  */
 class EarlReport {
   /**
    * Create an EARL Reporter.
    *
-   * @param options {Object} reporter options
-   *          env: {Object} environment description
+   * @param {object} options - Reporter options.
+   *   {object} env - Environment description.
    */
   constructor(options) {
     let today = new Date();

test/test.js

@@ -267,9 +267,9 @@ function _testsToMocha(tests) {
 /**
  * Adds the tests for all entries in the given manifest.
  *
- * @param manifest {Object} the manifest.
- * @param parent {Object} the parent test structure
- * @return {Promise}
+ * @param {object} manifest - The manifest.
+ * @param {object} parent - The parent test structure.
+ * @returns {Promise} - A promise with no value.
  */
 async function addManifest(manifest, parent) {
   // create test structure
@@ -324,10 +324,10 @@ async function addManifest(manifest, parent) {
 /**
  * Adds a test.
  *
- * @param manifest {Object} the manifest.
- * @param test {Object} the test.
- * @param tests {Array} the list of tests to add to.
- * @return {Promise}
+ * @param {object} manifest - The manifest.
+ * @param {object} test - The test.
+ * @param {Array} tests - The list of tests to add to.
+ * @returns {Promise} - A promise with no value.
  */
 async function addTest(manifest, test, tests) {
   // expand @id and input base