infra: lint all existing jsdocs (#2408)

.eslintrc.js

@@ -18,14 +18,15 @@ module.exports = defineConfig({
     'plugin:@typescript-eslint/recommended',
     'plugin:@typescript-eslint/recommended-type-checked',
     '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',
@@ -76,40 +77,39 @@ module.exports = defineConfig({
       { allowNumber: true, allowBoolean: true },
     ],
     '@typescript-eslint/unbound-method': 'off',
+
+    'jsdoc/no-types': 'error',
+    'jsdoc/require-jsdoc': 'off',
+    'jsdoc/require-returns': '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'] },
+        ],
+      },
+    ],
+    'jsdoc/tag-lines': 'off',
+  },
+  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',
       },
     },
     {

scripts/apidoc/apiDocsWriter.ts

@@ -199,7 +199,7 @@ export function writeApiDiffIndex(diffIndex: DocsApiDiffIndex): void {
 /**
  * Writes the api search index to the correct location.
  *
- * @param project The typedoc project.
+ * @param pages The pages to write into the index.
  */
 export function writeApiSearchIndex(pages: ModuleSummary[]): void {
   const apiIndex: APIGroup[] = [

scripts/apidoc/markdown.ts

@@ -47,7 +47,9 @@ function comparableSanitizedHtml(html: string): string {
 
 /**
  * Converts a Typescript code block to an HTML string and sanitizes it.
+ *
  * @param code The code to convert.
+ *
  * @returns The converted HTML string.
  */
 export function codeToHtml(code: string): string {
@@ -57,8 +59,10 @@ export function codeToHtml(code: string): string {
 
 /**
  * Converts Markdown to an HTML string and sanitizes it.
+ *
  * @param md The markdown to convert.
  * @param inline Whether to render the markdown as inline, without a wrapping `<p>` tag. Defaults to `false`.
+ *
  * @returns The converted HTML string.
  */
 export function mdToHtml(md: string, inline: boolean = false): string {

scripts/apidoc/moduleMethods.ts

@@ -23,6 +23,7 @@ import { adjustUrls } from './utils';
  * Analyzes and writes the documentation for modules and their methods such as `faker.animal.cat()`.
  *
  * @param project The project used to extract the modules.
+ *
  * @returns The generated pages.
  */
 export async function processModules(
@@ -35,6 +36,7 @@ export async function processModules(
  * Analyzes and writes the documentation for a module and its methods such as `faker.animal.cat()`.
  *
  * @param module The module to process.
+ *
  * @returns The generated pages.
  */
 async function processModule(
@@ -63,6 +65,7 @@ async function processModule(
  * Analyzes the documentation for a class.
  *
  * @param module The class to process.
+ *
  * @returns The class information.
  */
 export function analyzeModule(module: DeclarationReflection): {
@@ -85,6 +88,7 @@ export function analyzeModule(module: DeclarationReflection): {
  *
  * @param module The module to process.
  * @param accessor The code used to access the methods within the module.
+ *
  * @returns A list containing the documentation for the api methods in the given module.
  */
 export async function processModuleMethods(
@@ -99,6 +103,7 @@ export async function processModuleMethods(
  *
  * @param signatures The signatures to process.
  * @param accessor The code used to access the methods.
+ *
  * @returns A list containing the documentation for the api methods.
  */
 export async function processMethods(

scripts/apidoc/parameterDefaults.ts

@@ -18,6 +18,9 @@ interface ParameterDefaultsAware extends Reflection {
 
 /**
  * TypeDoc EventCallback for EVENT_CREATE_DECLARATION events that reads the default parameters from the implementation.
+ *
+ * @param context The converter context.
+ * @param reflection The reflection to read the default parameters from.
  */
 export const parameterDefaultReader: EventCallback = (
   context: Context,
@@ -44,6 +47,7 @@ export const parameterDefaultReader: EventCallback = (
  * Removes compile expressions that don't add any value for readers.
  *
  * @param value The default value to clean.
+ *
  * @returns The cleaned default value.
  */
 function cleanParameterDefault(value: string): string;

scripts/apidoc/signature.ts

@@ -314,6 +314,7 @@ async function signatureTypeToText(
  * Extracts and removed the parameter default from the comments.
  *
  * @param comment The comment to extract the default from.
+ *
  * @returns The extracted default value.
  */
 function extractDefaultFromComment(comment?: Comment): string | undefined {

scripts/apidoc/typedoc.ts

@@ -28,6 +28,7 @@ type CommentHolder = Pick<Reflection, 'comment'>;
  * Loads the project using TypeDoc.
  *
  * @param options The options to use for the project.
+ *
  * @returns The TypeDoc application and the project reflection.
  */
 export function loadProject(
@@ -75,6 +76,8 @@ function newTypeDocApp(): Application {
  * Selects the modules from the project that needs to be documented.
  *
  * @param project The project to extract the modules from.
+ * @param includeTestModules Whether to include test modules.
+ *
  * @returns The modules to document.
  */
 export function selectApiModules(
@@ -93,6 +96,7 @@ export function selectApiModules(
  * Selects the methods from the module that needs to be documented.
  *
  * @param module The module to extract the methods from.
+ *
  * @returns The methods to document.
  */
 export function selectApiMethods(
@@ -107,6 +111,7 @@ export function selectApiMethods(
  * Selects the signature from the method that needs to be documented.
  *
  * @param method The method to extract the signature from.
+ *
  * @returns The signature to document.
  */
 export function selectApiSignature(
@@ -124,7 +129,8 @@ export function selectApiSignature(
  * Selects the method signatures from the module that needs to be documented.
  * Method-Name -> Method-Signature
  *
- * @param method The module to extract the method signatures from.
+ * @param module The module to extract the method signatures from.
+ *
  * @returns The method signatures to document.
  */
 export function selectApiMethodSignatures(
@@ -206,6 +212,7 @@ export function extractSourcePath(
  *
  * @param tag The tag to extract the text from.
  * @param reflection The reflection to extract the text from.
+ * @param tagProcessor The function used to extract the text from the tag.
  */
 export function extractTagContent(
   tag: `@${string}`,
@@ -285,6 +292,8 @@ export function extractSeeAlsos(reflection?: CommentHolder): string[] {
 
 /**
  * Joins the parts of the given jsdocs tag.
+ *
+ * @param tag The tag to join the parts of.
  */
 export function joinTagContent(tag: CommentTag): string[] {
   return [joinTagParts(tag?.content)];

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>,