Add jsdoc-eslint plugin (#3937)

vufind-org · Oct 25, 2024 · f472b14 · f472b14
1 parent e4f564c
commit f472b14
Show file tree

Hide file tree

Showing 5 changed files with 141 additions and 18 deletions.
diff --git a/.eslintrc.jsdoc.js b/.eslintrc.jsdoc.js
@@ -0,0 +1,115 @@
+/**
+ * TODO: Temporary file for rules. Merge this file into eslintrc.js
+ * after all the ignored patterns under themes/bootstrap5/js are removed.
+ */
+module.exports = {
+  plugins: ["jsdoc"],
+  ignorePatterns: [
+    "themes/**/vendor/**",
+    "themes/**/node_modules/**",
+    "themes/bootstrap5/js/account_ajax.js",
+    "themes/bootstrap5/js/relais.js",
+    "themes/bootstrap5/js/search.js",
+    "themes/bootstrap5/js/requests.js",
+    "themes/bootstrap5/js/resultcount.js",
+    "themes/bootstrap5/js/map_tab_leaflet.js",
+    "themes/bootstrap5/js/check_item_statuses.js",
+    "themes/bootstrap5/js/combined-search.js",
+    "themes/bootstrap5/js/cart.js",
+    "themes/bootstrap5/js/pubdate_vis.js",
+    "themes/bootstrap5/js/map_selection_leaflet.js",
+    "themes/bootstrap5/js/common.js",
+    "themes/bootstrap5/js/bs3-compat.js",
+    "themes/bootstrap5/js/explain.js",
+    "themes/bootstrap5/js/list_item_selection.js",
+    "themes/bootstrap5/js/embedded_record.js",
+    "themes/bootstrap5/js/openurl.js",
+    "themes/bootstrap5/js/ill.js",
+    "themes/bootstrap5/js/record.js",
+    "themes/bootstrap5/js/doi.js",
+    "themes/bootstrap5/js/keep_alive.js",
+    "themes/bootstrap5/js/embedGBS.js",
+    "themes/bootstrap5/js/lib/ajax_request_queue.js",
+    "themes/bootstrap5/js/covers.js",
+    "themes/bootstrap5/js/trigger_print.js",
+    "themes/bootstrap5/js/visual_facets.js",
+    "themes/bootstrap5/js/preview.js",
+    "themes/bootstrap5/js/facets.js",
+    "themes/bootstrap5/js/searchbox_controls.js",
+    "themes/bootstrap5/js/lightbox.js",
+    "themes/bootstrap5/js/hierarchy_tree.js",
+    "themes/bootstrap5/js/cookie.js",
+    "themes/bootstrap5/js/record_versions.js",
+    "themes/bootstrap5/js/collection_record.js",
+    "themes/bootstrap5/js/sticky_elements.js",
+    "themes/bootstrap5/js/checkouts.js",
+    "themes/bootstrap5/js/advanced_search.js",
+    "themes/bootstrap5/js/check_save_statuses.js",
+    "themes/bootstrap5/js/hold.js",
+    "themes/bootstrap5/js/config.js",
+    "themes/bootstrap5/js/channels.js",
+    "themes/bootstrap5/js/truncate.js",
+    "themes/bootstrap3/**"
+  ],
+  extends: [],
+  env: {
+    "browser": true,
+    "es6": true,
+    "jquery": true
+  },
+  rules: {
+    // Recommended
+    "jsdoc/check-access": 1,
+    "jsdoc/check-alignment": 1,
+    "jsdoc/check-param-names": 1,
+    "jsdoc/check-property-names": 1,
+    "jsdoc/check-tag-names": 1,
+    "jsdoc/check-types": 1,
+    "jsdoc/check-values": 1,
+    "jsdoc/empty-tags": 1,
+    "jsdoc/implements-on-classes": 1,
+    "jsdoc/multiline-blocks": 1,
+    "jsdoc/no-multi-asterisks": 1,
+    "jsdoc/no-undefined-types": 1,
+    "jsdoc/require-jsdoc": 1,
+    "jsdoc/require-param": 1,
+    "jsdoc/require-param-description": 1,
+    "jsdoc/require-param-name": 1,
+    "jsdoc/require-param-type": 1,
+    "jsdoc/require-property": 1,
+    "jsdoc/require-property-description": 1,
+    "jsdoc/require-property-name": 1,
+    "jsdoc/require-property-type": 1,
+    "jsdoc/require-returns": 1,
+    "jsdoc/require-returns-check": 1,
+    "jsdoc/require-returns-description": 1,
+    "jsdoc/require-returns-type": 1,
+    "jsdoc/require-yields": 1,
+    "jsdoc/require-yields-check": 1,
+    "jsdoc/tag-lines": 1,
+    "jsdoc/valid-types": 1
+    // Disabled
+    //"jsdoc/check-examples": 1,
+    //"jsdoc/check-indentation": 1,
+    //"jsdoc/check-line-alignment": 1,
+    //"jsdoc/check-template-names": 1,
+    //"jsdoc/check-syntax": 1,
+    //"jsdoc/informative-docs": 1,
+    //"jsdoc/match-description": 1,
+    //"jsdoc/no-bad-blocks": 1,
+    //"jsdoc/no-blank-block-descriptions": 1,
+    //"jsdoc/no-defaults": 1,
+    //"jsdoc/no-missing-syntax": 1,
+    //"jsdoc/no-restricted-syntax": 1,
+    //"jsdoc/no-types": 1,
+    //"jsdoc/require-asterisk-prefix": 1,
+    //"jsdoc/require-description": 1,
+    //"jsdoc/require-description-complete-sentence": 1,
+    //"jsdoc/require-example": 1,
+    //"jsdoc/require-file-overview": 1,
+    //"jsdoc/require-hyphen-before-param-description": 1,
+    //"jsdoc/require-template": 1,
+    //"jsdoc/require-throws": 1,
+    //"jsdoc/sort-tags": 1,
+  }
+};
diff --git a/build.xml b/build.xml
@@ -155,6 +155,7 @@
   <!-- Quality Assurance Javascript Tasks -->
   <target name="qa-js-and-less" description="quality assurance js and less tasks">
     <phingcall target="eslint"/>
+    <phingcall target="eslint-jsdoc"/>
     <phingcall target="jshint"/>
     <phingcall target="checkLessToSass"/>
     <phingcall target="checkSassBuild"/>
@@ -276,6 +277,20 @@
     </exec>
   </target>
 
+  <!-- ESLint jsDoc (test only) -->
+  <target name="eslint-jsdoc">
+    <exec executable="npx" escape="false" checkreturn="true" passthru="true">
+      <arg line="eslint ${srcdir}/themes/**/*.js -c ${srcdir}/.eslintrc.jsdoc.js" />
+    </exec>
+  </target>
+
+  <!-- ESLint jsDoc (auto-fix eligible issues) -->
+  <target name="eslint-jsdoc-fix">
+    <exec executable="npx" escape="false" checkreturn="true" passthru="true">
+      <arg line="eslint ${srcdir}/themes/**/*.js -c ${srcdir}/.eslintrc.jsdoc.js --fix" />
+    </exec>
+  </target>
+
   <!-- JSHint -->
   <target name="jshint">
     <exec executable="npx" checkreturn="true" passthru="true">

diff --git a/package.json b/package.json
@@ -45,6 +45,7 @@
   "devDependencies": {
     "all-iso-language-codes": "^1.0.13",
     "eslint": "^8.15.0",
+    "eslint-plugin-jsdoc": "50.2.2",
     "eslint-plugin-no-jquery": "^2.7.0",
     "grunt-contrib-watch": "^1.1.0",
     "jshint": "^2.13.4"

diff --git a/themes/bootstrap3/js/observer_manager.js b/themes/bootstrap3/js/observer_manager.js
@@ -8,8 +8,7 @@ VuFind.register('observerManager', () => {
 
   /**
    * Observe given elements. Observer used is identified with identifier.
-   *
-   * @param {String}         identifier Observers identifier
+   * @param {string}         identifier Observers identifier
    * @param {Array|NodeList} elements   Elements to observe
    */
   function observe(identifier, elements) {
@@ -31,13 +30,11 @@ VuFind.register('observerManager', () => {
    * Create an IntersectionObserver.
    * If the IntersectionObserver is not supported, onIntersect will be used as a
    * standalone function.
-   *
-   * @link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API 
-   *
-   * @param {String}         identifier  Id of the observer to create
+   * Documentation {@link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API} 
+   * @param {string}         identifier  Id of the observer to create
    * @param {Function}       onIntersect Callback to use on elements
    * @param {Array|NodeList} elements    Initial elements to be observed
-   * @param {Object}         options     Options for the Intersection Observer
+   * @param {object}         options     Options for the Intersection Observer
    */
   function createIntersectionObserver(identifier, onIntersect, elements, options) {
     if (typeof observers[identifier] === 'undefined') {
@@ -73,8 +70,7 @@ VuFind.register('observerManager', () => {
 
   /**
    * Remove an observer.
-   *
-   * @param {String} identifier Identifier of observer to remove
+   * @param {string} identifier Identifier of observer to remove
    */
   function disconnect(identifier) {
     if (typeof observers[identifier] !== 'undefined'

diff --git a/themes/bootstrap5/js/observer_manager.js b/themes/bootstrap5/js/observer_manager.js
@@ -8,8 +8,7 @@ VuFind.register('observerManager', () => {
 
   /**
    * Observe given elements. Observer used is identified with identifier.
-   *
-   * @param {String}         identifier Observers identifier
+   * @param {string}         identifier Observers identifier
    * @param {Array|NodeList} elements   Elements to observe
    */
   function observe(identifier, elements) {
@@ -31,13 +30,11 @@ VuFind.register('observerManager', () => {
    * Create an IntersectionObserver.
    * If the IntersectionObserver is not supported, onIntersect will be used as a
    * standalone function.
-   *
-   * @link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API 
-   *
-   * @param {String}         identifier  Id of the observer to create
+   * Documentation {@link https://developer.mozilla.org/en-US/docs/Web/API/Intersection_Observer_API} 
+   * @param {string}         identifier  Id of the observer to create
    * @param {Function}       onIntersect Callback to use on elements
    * @param {Array|NodeList} elements    Initial elements to be observed
-   * @param {Object}         options     Options for the Intersection Observer
+   * @param {object}         options     Options for the Intersection Observer
    */
   function createIntersectionObserver(identifier, onIntersect, elements, options) {
     if (typeof observers[identifier] === 'undefined') {
@@ -73,8 +70,7 @@ VuFind.register('observerManager', () => {
 
   /**
    * Remove an observer.
-   *
-   * @param {String} identifier Identifier of observer to remove
+   * @param {string} identifier Identifier of observer to remove
    */
   function disconnect(identifier) {
     if (typeof observers[identifier] !== 'undefined'