chore: add eslint-jsdoc-plugin to eslint (#1585)

This plugin helps us detect some things the built-in jsdoc rules can't,
like whether there is an example or not.

As expected, the addition of this plugin helped detect some minor JSDoc
issues.

Signed-off-by: Juan Cruz Viotti <jv@jviotti.com>

.eslintrc.yml

@@ -6,7 +6,13 @@ env:
   mocha: true
 plugins:
   - lodash
+  - jsdoc
 extends: 'eslint:recommended'
+settings:
+  jsdoc:
+    additionalTagNames:
+      customTags:
+        - fulfil
 rules:
 
   # Possible Errors
@@ -645,3 +651,24 @@ rules:
     - error
   lodash/prefer-times:
     - error
+
+  # JSDoc
+
+  jsdoc/check-param-names:
+    - error
+  jsdoc/check-tag-names:
+    - error
+  jsdoc/newline-after-description:
+    - error
+  jsdoc/require-example:
+    - error
+  jsdoc/require-hyphen-before-param-description:
+    - error
+  jsdoc/require-param:
+    - error
+  jsdoc/require-param-description:
+    - error
+  jsdoc/require-param-type:
+    - error
+  jsdoc/require-returns-type:
+    - error

lib/gui/components/safe-webview.js

@@ -16,6 +16,8 @@
 
 'use strict';
 
+/* eslint-disable jsdoc/require-example */
+
 const _ = require('lodash');
 const electron = require('electron');
 const angular = require('angular');

lib/gui/components/svg-icon.js

@@ -16,6 +16,8 @@
 
 'use strict';
 
+/* eslint-disable jsdoc/require-example */
+
 /**
  * @module Etcher.Components.SVGIcon
  */

lib/gui/pages/settings/controllers/settings.js

@@ -36,6 +36,9 @@ module.exports = function(WarningModalService) {
    * @summary Refresh current settings
    * @function
    * @public
+   *
+   * @example
+   * SettingsController.refreshSettings();
    */
   this.refreshSettings = () => {
     this.currentData = settings.getAll();

lib/image-stream/archive.js

@@ -60,6 +60,7 @@ const IMAGE_EXTENSIONS = _.reduce(supportedFileTypes, (accumulator, file) => {
  * @fulfil {*} contents
  * @returns {Promise}
  *
+ * @example
  * extractEntryByPath('my/archive.zip', '_info/logo.svg', {
  *   hooks: { ... },
  *   entries: [ ... ],
@@ -98,6 +99,7 @@ const extractEntryByPath = (archive, filePath, options) => {
  * @fulfil {Object} - metadata
  * @returns {Promise}
  *
+ * @example
  * extractArchiveMetadata('my/archive.zip', '.meta', {
  *   hooks: { ... },
  *   entries: [ ... ]

lib/image-stream/handlers.js

@@ -16,6 +16,8 @@
 
 'use strict';
 
+/* eslint-disable jsdoc/require-example */
+
 const Bluebird = require('bluebird');
 const fs = Bluebird.promisifyAll(require('fs'));
 const PassThroughStream = require('stream').PassThrough;

lib/image-stream/parse-partitions.js

@@ -152,7 +152,6 @@ const parsePartitionTables = (image, buffer) => {
  * @param {Object} image - image metadata
  * @returns {Promise}
  * @fulfil {Object} image
- * @reject {Error}
  *
  * @example
  * parsePartitions(image)

lib/shared/supported-formats.js

@@ -47,6 +47,7 @@ const getExtensionsFromTypeGetter = (type) => {
  *
  * @returns {String[]} compressed extensions
  *
+ * @example
  * _.each(supportedFormats.getCompressedExtensions(), (extension) => {
  *   console.log('We support the ' + extension + ' compressed file format');
  * });
@@ -60,6 +61,7 @@ exports.getCompressedExtensions = getExtensionsFromTypeGetter('compressed');
  *
  * @returns {String[]} no compressed extensions
  *
+ * @example
  * _.each(supportedFormats.getNonCompressedExtensions(), (extension) => {
  *   console.log('We support the ' + extension + ' file format');
  * });
@@ -73,6 +75,7 @@ exports.getNonCompressedExtensions = getExtensionsFromTypeGetter('image');
  *
  * @returns {String[]} archive extensions
  *
+ * @example
  * _.each(supportedFormats.getArchiveExtensions(), (extension) => {
  *   console.log('We support the ' + extension + ' file format');
  * });
@@ -86,6 +89,7 @@ exports.getArchiveExtensions = getExtensionsFromTypeGetter('archive');
  *
  * @returns {String[]} extensions
  *
+ * @example
  * _.each(supportedFormats.getAllExtensions(), (extension) => {
  *   console.log('We support the ' + extension + ' format');
  * });
@@ -102,6 +106,7 @@ exports.getAllExtensions = () => {
  * @param {String} imagePath - image path
  * @returns {Boolean} whether the image is supported
  *
+ * @example
  * if (supportedFormats.isSupportedImage('foo.iso.bz2')) {
  *   console.log('The image is supported!');
  * }

npm-shrinkwrap.json

@@ -863,6 +863,12 @@
       "from": "commander@>=2.8.1 <2.9.0",
       "resolved": "https://registry.npmjs.org/commander/-/commander-2.8.1.tgz"
     },
+    "comment-parser": {
+      "version": "0.4.0",
+      "from": "comment-parser@>=0.4.0 <0.5.0",
+      "resolved": "https://registry.npmjs.org/comment-parser/-/comment-parser-0.4.0.tgz",
+      "dev": true
+    },
     "commoner": {
       "version": "0.10.8",
       "from": "commoner@>=0.10.3 <0.11.0",
@@ -1910,6 +1916,12 @@
         }
       }
     },
+    "eslint-plugin-jsdoc": {
+      "version": "3.1.1",
+      "from": "eslint-plugin-jsdoc@latest",
+      "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-3.1.1.tgz",
+      "dev": true
+    },
     "eslint-plugin-lodash": {
       "version": "2.3.6",
       "from": "eslint-plugin-lodash@2.3.6",

package.json

@@ -87,6 +87,7 @@
     "electron-builder": "19.9.1",
     "electron-mocha": "3.3.0",
     "eslint": "3.18.0",
+    "eslint-plugin-jsdoc": "^3.1.1",
     "eslint-plugin-lodash": "2.3.6",
     "file-exists": "1.0.0",
     "html-angular-validate": "0.1.9",