chore: turn on jsdoc linting for existing jsdoc in all files

Author: ST-DDT

.eslintrc.js

@@ -18,14 +18,15 @@ module.exports = defineConfig({
     'plugin:@typescript-eslint/recommended',
     'plugin:@typescript-eslint/recommended-requiring-type-checking',
     'plugin:prettier/recommended',
+    'plugin:jsdoc/recommended-typescript-error',
   ],
   parser: '@typescript-eslint/parser',
   parserOptions: {
     project: ['./tsconfig.json'],
     sourceType: 'module',
     warnOnUnsupportedTypeScriptVersion: false,
   },
-  plugins: ['@typescript-eslint', 'prettier', 'deprecation'],
+  plugins: ['@typescript-eslint', 'prettier', 'deprecation', 'jsdoc'],
   rules: {
     // We may want to use this in the future
     'no-useless-escape': 'off',
@@ -77,40 +78,39 @@ module.exports = defineConfig({
       { allowNumber: true, allowBoolean: true },
     ],
     '@typescript-eslint/unbound-method': 'off',
+
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/no-types': 'error',
+    'jsdoc/require-returns': 'off',
+    'jsdoc/tag-lines': 'off',
+    'jsdoc/sort-tags': [
+      'error',
+      {
+        tagSequence: [
+          { tags: ['template'] },
+          { tags: ['internal'] },
+          { tags: ['param'] },
+          { tags: ['returns'] },
+          { tags: ['throws'] },
+          { tags: ['see'] },
+          { tags: ['example'] },
+          { tags: ['since'] },
+          { tags: ['default'] },
+          { tags: ['deprecated'] },
+        ],
+      },
+    ],
+  },
+  settings: {
+    jsdoc: {
+      mode: 'typescript',
+    },
   },
   overrides: [
     {
       files: ['src/**/*.ts'],
-      plugins: ['jsdoc'],
-      extends: ['plugin:jsdoc/recommended-error'],
       rules: {
-        'jsdoc/no-types': 'error',
-        'jsdoc/require-param-type': 'off',
-        'jsdoc/require-returns-type': 'off',
-        'jsdoc/require-returns': 'off',
-        'jsdoc/tag-lines': 'off',
-        'jsdoc/sort-tags': [
-          'error',
-          {
-            tagSequence: [
-              { tags: ['template'] },
-              { tags: ['internal'] },
-              { tags: ['param'] },
-              { tags: ['returns'] },
-              { tags: ['throws'] },
-              { tags: ['see'] },
-              { tags: ['example'] },
-              { tags: ['since'] },
-              { tags: ['default'] },
-              { tags: ['deprecated'] },
-            ],
-          },
-        ],
-      },
-      settings: {
-        jsdoc: {
-          mode: 'typescript',
-        },
+        'jsdoc/require-jsdoc': 'error',
       },
     },
     {

src/modules/date/index.ts

@@ -23,6 +23,9 @@ function toDate(
   return date;
 }
 
+/**
+ * Module to generate dates (without methods requiring localized data).
+ */
 export class SimpleDateModule {
   constructor(protected readonly faker: SimpleFaker) {
     bindThisToMemberFunctions(this);

src/modules/helpers/index.ts

@@ -158,6 +158,9 @@ function legacyRegexpStringParse(
   return string;
 }
 
+/**
+ * Module with various helper methods providing basic (seed-dependent) operations useful for implementing faker methods (without methods requiring localized data).
+ */
 export class SimpleHelpersModule {
   /**
    * Global store of unique values.

test/modules/location.spec.ts

@@ -12,7 +12,9 @@ function kilometersToMiles(miles: number) {
 }
 
 /**
- * Returns the number of decimal places a number has
+ * Returns the number of decimal places a number has.
+ *
+ * @param num The number to check.
  */
 function precision(num: number): number {
   const decimalPart = num.toString().split('.')[1];

test/scripts/apidoc/__snapshots__/signature.spec.ts.snap

@@ -43,7 +43,7 @@ exports[`signature > analyzeSignature() > complexArrayParameter 1`] = `
   "returns": "T",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L357",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L358",
   "throws": undefined,
 }
 `;
@@ -198,7 +198,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecated 1`] = `
     "test.apidoc.methodWithExample()",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L277",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L278",
   "throws": undefined,
 }
 `;
@@ -250,7 +250,7 @@ exports[`signature > analyzeSignature() > methodWithDeprecatedOption 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L298",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L299",
   "throws": undefined,
 }
 `;
@@ -268,7 +268,7 @@ exports[`signature > analyzeSignature() > methodWithExample 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L266",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L267",
   "throws": undefined,
 }
 `;
@@ -288,7 +288,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkers 1`] = `
     "test.apidoc.methodWithDeprecated()",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L325",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L326",
   "throws": undefined,
 }
 `;
@@ -308,7 +308,7 @@ exports[`signature > analyzeSignature() > methodWithMultipleSeeMarkersAndBacktic
     "test.apidoc.methodWithDeprecated() with parameter <code>bar</code> and <code>baz</code>.",
   ],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L335",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L336",
   "throws": undefined,
 }
 `;
@@ -325,7 +325,7 @@ exports[`signature > analyzeSignature() > methodWithSinceMarker 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "1.0.0",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L344",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L345",
   "throws": undefined,
 }
 `;
@@ -342,7 +342,7 @@ exports[`signature > analyzeSignature() > methodWithThrows 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L286",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L287",
   "throws": "a Faker error",
 }
 `;
@@ -491,7 +491,7 @@ It also has a more complex description.</p>
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L216",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L217",
   "throws": undefined,
 }
 `;
@@ -530,7 +530,7 @@ exports[`signature > analyzeSignature() > optionsInterfaceParamMethodWithDefault
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L252",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L253",
   "throws": undefined,
 }
 `;
@@ -596,7 +596,7 @@ exports[`signature > analyzeSignature() > optionsParamMethod 1`] = `
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L186",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L187",
   "throws": undefined,
 }
 `;
@@ -635,7 +635,7 @@ exports[`signature > analyzeSignature() > optionsTypeParamMethodWithDefaults 1`]
   "returns": "number",
   "seeAlsos": [],
   "since": "",
-  "sourcePath": "test/scripts/apidoc/signature.example.ts#L234",
+  "sourcePath": "test/scripts/apidoc/signature.example.ts#L235",
   "throws": undefined,
 }
 `;

test/scripts/apidoc/signature.example.ts

@@ -182,6 +182,7 @@ export class SignatureTest {
    * @param options.b The string parameter.
    * @param options.c The boolean parameter.
    * @param options.d The method parameter.
+   * @param options.e The LiteralUnion parameter.
    */
   optionsParamMethod(options: {
     a: number;

test/scripts/apidoc/utils.ts

@@ -12,6 +12,9 @@ import { mapByName } from '../../../scripts/apidoc/utils';
 
 /**
  * Returns a record with the (Module-Name -> (Method-Name -> Method-Signature)) for the project.
+ *
+ * @param options The TypeDoc options.
+ * @param includeTestModules Whether to include the test modules.
  */
 export function loadProjectModules(
   options?: Partial<TypeDocOptions>,

test/support/times.ts

@@ -2,6 +2,7 @@
  * Generates a number sequence from 1 to `length`.
  *
  * @param length The length of the sequence.
+ *
  * @returns The sequence.
  */
 export function times(length: number): number[] {