From 767b2dcc2b3c4c502bd0979b8d52e708c8b11bdb Mon Sep 17 00:00:00 2001 From: "David I. Lehn" Date: Thu, 22 Jun 2023 23:29:12 -0400 Subject: [PATCH] Add eslint jsdoc support. - Add eslint jsdoc support. - Fix lint issues. --- .eslintrc.js | 6 ++++- lib/IdentifierIssuer.js | 21 ++++++++-------- lib/MessageDigest-webcrypto.js | 2 +- lib/MessageDigest.js | 2 +- lib/NQuads.js | 46 +++++++++++++++++++++------------- lib/Permuter.js | 6 ++--- lib/index.js | 10 +++++--- package.json | 1 + test/.eslintrc.js | 3 --- test/EarlReport.js | 8 +++--- test/test.js | 14 +++++------ 11 files changed, 67 insertions(+), 52 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index f1f2281..d2743a7 100644 --- a/.eslintrc.js +++ b/.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' ] diff --git a/lib/IdentifierIssuer.js b/lib/IdentifierIssuer.js index aad41b2..2d94616 100644 --- a/lib/IdentifierIssuer.js +++ b/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 (''). - * @param existing an existing Map to use. - * @param counter the counter to use. + * @param {string} prefix - The prefix to use (''). + * @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()]; diff --git a/lib/MessageDigest-webcrypto.js b/lib/MessageDigest-webcrypto.js index b37d342..882aabd 100644 --- a/lib/MessageDigest-webcrypto.js +++ b/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 diff --git a/lib/MessageDigest.js b/lib/MessageDigest.js index d881185..9ae881b 100644 --- a/lib/MessageDigest.js +++ b/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); diff --git a/lib/NQuads.js b/lib/NQuads.js index 25666c3..ca0f9f2 100644 --- a/lib/NQuads.js +++ b/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)) { diff --git a/lib/Permuter.js b/lib/Permuter.js index 7a4c8ab..c77c710 100644 --- a/lib/Permuter.js +++ b/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 diff --git a/lib/index.js b/lib/index.js index 4b13ba9..9301f56 100644 --- a/lib/index.js +++ b/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} - 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} - A Promise that resolves to the canonicalized + * RDF Dataset. */ exports._canonizeSync = function(input, options) { const dataset = _inputToDataset(input, options); diff --git a/package.json b/package.json index a615331..6304e5a 100644 --- a/package.json +++ b/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", diff --git a/test/.eslintrc.js b/test/.eslintrc.js index e48cd25..bf3479f 100644 --- a/test/.eslintrc.js +++ b/test/.eslintrc.js @@ -1,8 +1,5 @@ module.exports = { env: { mocha: true - }, - globals: { - phantom: true } }; diff --git a/test/EarlReport.js b/test/EarlReport.js index f54a7dc..e5ebb32 100644 --- a/test/EarlReport.js +++ b/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(); diff --git a/test/test.js b/test/test.js index 9447abd..2493efa 100644 --- a/test/test.js +++ b/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