Merge pull request #205 from kazizi55/feature/inplement-eslint-jsdoc

chore: add eslint-plugin-jsdoc

Author: fabian-hiller

library/.eslintrc.cjs

@@ -4,6 +4,7 @@ module.exports = {
   extends: [
     'eslint:recommended',
     'plugin:@typescript-eslint/recommended',
+    'plugin:jsdoc/recommended-typescript-error',
     'plugin:regexp/recommended',
     'plugin:security/recommended',
   ],
@@ -41,6 +42,38 @@ module.exports = {
     '@typescript-eslint/consistent-type-imports': 'warn',
     '@typescript-eslint/no-non-null-assertion': 'off',
 
+    // Imports
+    'no-duplicate-imports': 'off',
+    'import/extensions': ['error', 'always'],
+
+    // JSDoc
+    'jsdoc/tag-lines': ['error', 'any', { startLines: 1 }],
+    'jsdoc/sort-tags': [
+      'error',
+      {
+        linesBetween: 1,
+        tagSequence: [
+          { tags: ['deprecated'] },
+          { tags: ['param'] },
+          { tags: ['returns'] },
+        ],
+      },
+    ],
+    // NOTE: For overloads functions, we only require a JSDoc at the top
+    // SEE: https://github.com/gajus/eslint-plugin-jsdoc/issues/666
+    'jsdoc/require-jsdoc': [
+      'error',
+      {
+        contexts: [
+          'ExportNamedDeclaration[declaration.type="TSDeclareFunction"]:not(ExportNamedDeclaration[declaration.type="TSDeclareFunction"] + ExportNamedDeclaration[declaration.type="TSDeclareFunction"])',
+          'ExportNamedDeclaration[declaration.type="FunctionDeclaration"]:not(ExportNamedDeclaration[declaration.type="TSDeclareFunction"] + ExportNamedDeclaration[declaration.type="FunctionDeclaration"])',
+        ],
+        require: {
+          FunctionDeclaration: false,
+        },
+      },
+    ],
+
     // Security
     'security/detect-object-injection': 'off', // Too many false positives
     'security/detect-unsafe-regex': 'off', // Too many false positives, see https://github.com/eslint-community/eslint-plugin-security/issues/28 - we use the redos-detector plugin instead

library/CHANGELOG.md

@@ -5,6 +5,7 @@ All notable changes to the library will be documented in this file.
 ## vX.X.X (Month DD, YYYY)
 
 - Change structure of schemas, validations and transformations to make properties accessible (pull request #211)
+- Fix errors in JSDoc comments and add JSDoc ESLint plugin (pull request #205)
 
 ## v0.20.1 (November 2, 2023)
 

library/package.json

@@ -58,6 +58,7 @@
     "@vitest/coverage-v8": "^0.33.0",
     "eslint": "^8.43.0",
     "eslint-plugin-import": "^2.28.1",
+    "eslint-plugin-jsdoc": "^46.8.2",
     "eslint-plugin-redos-detector": "^2.1.1",
     "eslint-plugin-regexp": "^1.15.0",
     "eslint-plugin-security": "^1.7.1",

library/src/methods/brand/brand.ts

@@ -39,7 +39,7 @@ export type SchemaWithBrand<
  * Brands the output type of a schema.
  *
  * @param schema The scheme to be branded.
- * @param brand The brand name.
+ * @param name The brand name.
  *
  * @returns The branded schema.
  */

library/src/schemas/nullish/nullish.ts

@@ -33,7 +33,6 @@ export type NullishSchema<
  * Creates a nullish schema.
  *
  * @param wrapped The wrapped schema.
- * @param default_ The default value.
  *
  * @returns A nullish schema.
  */

library/src/schemas/union/unionAsync.ts

@@ -41,7 +41,7 @@ export type UnionSchemaAsync<
 /**
  * Creates an async union schema.
  *
- * @param union The union options.
+ * @param options The union options.
  * @param message The error message.
  *
  * @returns An async union schema.

library/src/types/pipe.ts

@@ -47,11 +47,11 @@ export type BaseValidation<TInput = any> = {
   /**
    * Parses unknown input based on its requirement.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: TInput): PipeResult<TInput>;
 };
@@ -71,11 +71,11 @@ export type BaseValidationAsync<TInput = any> = {
   /**
    * Parses unknown input based on its requirement.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: TInput): Promise<PipeResult<TInput>>;
 };
@@ -91,11 +91,11 @@ export type BaseTransformation<TInput = any> = {
   /**
    * Parses unknown input based on its requirement.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: TInput): PipeResult<TInput>;
 };
@@ -111,11 +111,11 @@ export type BaseTransformationAsync<TInput = any> = {
   /**
    * Parses unknown input based on its requirement.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: TInput): Promise<PipeResult<TInput>>;
 };

library/src/types/schema.ts

@@ -43,18 +43,18 @@ export type BaseSchema<TInput = any, TOutput = TInput> = {
   /**
    * Parses unknown input based on its schema.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    * @param info The parse info.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: unknown, info?: ParseInfo): _ParseResult<TOutput>;
   /**
    * Input and output type.
    *
-   * @internal This is an internal API.
+   * @internal
    */
   _types?: { input: TInput; output: TOutput };
 };
@@ -70,18 +70,18 @@ export type BaseSchemaAsync<TInput = any, TOutput = TInput> = {
   /**
    * Parses unknown input based on its schema.
    *
-   * @internal This is an internal API.
-   *
    * @param input The input to be parsed.
    * @param info The parse info.
    *
    * @returns The parse result.
+   *
+   * @internal
    */
   _parse(input: unknown, info?: ParseInfo): Promise<_ParseResult<TOutput>>;
   /**
    * Input and output type.
    *
-   * @internal This is an internal API.
+   * @internal
    */
   _types?: { input: TInput; output: TOutput };
 };

library/src/utils/executePipe/executePipeAsync.ts

@@ -15,7 +15,7 @@ import { getIssue, getPipeInfo } from './utils/index.ts';
  *
  * @param input The input value.
  * @param pipe The pipe to be executed.
- * @param parseInfo The validation info.
+ * @param parseInfo The parse info.
  * @param reason The issue reason.
  *
  * @returns The output value.

library/src/utils/getPipeIssues/getPipeIssues.ts

@@ -8,6 +8,7 @@ import { getIssues } from '../getIssues/getIssues.ts';
  * @param validation The validation name.
  * @param message The error message.
  * @param input The input value.
+ * @param requirement The requirement.
  *
  * @returns The pipeline result object.
  */