feat: add jsdoc lint

conceptadev · Jul 3, 2024 · b015e10 · b015e10
1 parent ebe52aa
commit b015e10
Show file tree

Hide file tree

Showing 89 changed files with 174 additions and 268 deletions.
diff --git a/.eslintrc.js b/.eslintrc.js
@@ -11,6 +11,7 @@ module.exports = {
   ],
   extends: [
     '@concepta/eslint-config/nest',
+    'plugin:jsdoc/recommended-typescript',
   ],
   ignorePatterns: [
     'packages/*/dist/**',
@@ -40,11 +41,20 @@ module.exports = {
         jsonSyntax: 'JSON',
       },
     },
+    {
+      files: ['*.ts'],
+      rules: {
+        'jsdoc/require-jsdoc': 'off',
+        'jsdoc/require-param': 'off',
+        'jsdoc/require-returns': 'off',
+      },
+    },
     {
       files: ['*.spec.ts', '*.fixture.ts'],
       rules: {
         '@darraghor/nestjs-typed/controllers-should-supply-api-tags': 'off',
         '@darraghor/nestjs-typed/api-method-should-specify-api-response': 'off',
+        'plugin:jsdoc/recommended-typescript': 'off',
         'tsdoc/syntax': 'off',
       },
     },

diff --git a/package.json b/package.json
@@ -29,6 +29,7 @@
     "eslint": "^8.6.0",
     "eslint-config-prettier": "^8.3.0",
     "eslint-plugin-import": "^2.25.4",
+    "eslint-plugin-jsdoc": "^48.5.0",
     "eslint-plugin-node": "^11.1.0",
     "eslint-plugin-prettier": "^4.0.0",
     "eslint-plugin-tsdoc": "^0.3.0",

diff --git a/packages/nestjs-access-control/src/decorators/access-control-create-many.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-create-many.decorator.ts
@@ -2,8 +2,7 @@ import { AccessControlCreateOne } from './access-control-create-one.decorator';
 
 /**
  * Create many resource grant shortcut.
- *
- * @param string - resource The grant resource.
+ * @param resource - The grant resource.
  */
 export const AccessControlCreateMany = (resource: string) =>
   AccessControlCreateOne(resource);
diff --git a/packages/nestjs-access-control/src/decorators/access-control-create-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-create-one.decorator.ts
@@ -4,8 +4,7 @@ import { applyDecorators } from '@nestjs/common';
 
 /**
  * Create one resource grant shortcut.
- *
- * @param string - resource The grant resource.
+ * @param resource - The grant resource.
  * @returns Decorator function
  */
 export const AccessControlCreateOne = (

diff --git a/packages/nestjs-access-control/src/decorators/access-control-delete-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-delete-one.decorator.ts
@@ -3,9 +3,8 @@ import { applyDecorators } from '@nestjs/common';
 import { ActionEnum } from '../enums/action.enum';
 
 /**
- * Delete one resource grant shortcut
- *
- * @param string - resource The grant resource.
+ * Delete one resource grant shortcut.
+ * @param resource - The grant resource.
  * @returns Decorator function
  */
 export const AccessControlDeleteOne = (

diff --git a/packages/nestjs-access-control/src/decorators/access-control-grant.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-grant.decorator.ts
@@ -4,7 +4,6 @@ import { ACCESS_CONTROL_MODULE_GRANT_METADATA } from '../constants';
 
 /**
  * Define access control grants required for this route.
- *
  * @param acGrants - Array of access control grants.
  * @returns Decorator function.
  */

diff --git a/packages/nestjs-access-control/src/decorators/access-control-query.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-query.decorator.ts
@@ -4,7 +4,6 @@ import { ACCESS_CONTROL_MODULE_QUERY_METADATA } from '../constants';
 
 /**
  * Define access query options for this route.
- *
  * @param queryOptions - Array of access control query options.
  * @returns Decorator function.
  */

diff --git a/packages/nestjs-access-control/src/decorators/access-control-read-many.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-read-many.decorator.ts
@@ -4,8 +4,7 @@ import { AccessControlGrant } from './access-control-grant.decorator';
 
 /**
  * Read many resource grant shortcut.
- *
- * @param string - resource The grant resource.
+ * @param resource - The grant resource.
  * @returns Decorator function
  */
 export const AccessControlReadMany = (

diff --git a/packages/nestjs-access-control/src/decorators/access-control-read-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-read-one.decorator.ts
@@ -4,8 +4,7 @@ import { AccessControlGrant } from './access-control-grant.decorator';
 
 /**
  * Read one resource grant shortcut
- *
- * @param string - resource The grant resource.
+ * @param resource - The grant resource.
  * @returns Decorator function
  */
 export const AccessControlReadOne = (

diff --git a/packages/nestjs-access-control/src/decorators/access-control-recover-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-recover-one.decorator.ts
@@ -2,8 +2,7 @@ import { AccessControlCreateOne } from './access-control-create-one.decorator';
 
 /**
  * Recover one resource grant shortcut.
- *
- * @param string - resource The grant resource.
+ * @param resource - The grant resource.
  */
 export const AccessControlRecoverOne = (resource: string) =>
   AccessControlCreateOne(resource);
diff --git a/packages/nestjs-access-control/src/decorators/access-control-replace-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-replace-one.decorator.ts
@@ -1,9 +1,8 @@
 import { AccessControlUpdateOne } from './access-control-update-one.decorator';
 
 /**
- * Update one resource grant shortcut
- *
- * @param string - resource The grant resource.
+ * Update one resource grant shortcut.
+ * @param resource - The grant resource.
  */
 export const AccessControlReplaceOne = (resource: string) =>
   AccessControlUpdateOne(resource);
diff --git a/packages/nestjs-access-control/src/decorators/access-control-update-one.decorator.ts b/packages/nestjs-access-control/src/decorators/access-control-update-one.decorator.ts
@@ -3,9 +3,8 @@ import { ActionEnum } from '../enums/action.enum';
 import { AccessControlGrant } from './access-control-grant.decorator';
 
 /**
- * Update one resource grant shortcut
- *
- * @param string - resource The grant resource.
+ * Update one resource grant shortcut.
+ * @param resource - The grant resource.
  * @returns Decorator function
  */
 export const AccessControlUpdateOne = (

diff --git a/packages/nestjs-auth-jwt/src/auth-jwt.strategy.ts b/packages/nestjs-auth-jwt/src/auth-jwt.strategy.ts
@@ -45,7 +45,6 @@ export class AuthJwtStrategy extends PassportStrategyFactory<JwtStrategy>(
 
   /**
    * Validate the user based on payload sub
-   *
    * @param payload - The payload to validate
    */
   async validate(

diff --git a/packages/nestjs-auth-local/src/auth-local.strategy.ts b/packages/nestjs-auth-local/src/auth-local.strategy.ts
@@ -30,10 +30,8 @@ export class AuthLocalStrategy extends PassportStrategyFactory<Strategy>(
   AUTH_LOCAL_STRATEGY_NAME,
 ) {
   /**
-   *
-   * @param userLookupService - The service used to get the user
    * @param settings - The settings for the local strategy
-   * @param passwordStorageService - The service used to hash and validate passwords
+   * @param validateUserService - The service used validate passwords
    */
   constructor(
     @Inject(AUTH_LOCAL_MODULE_SETTINGS_TOKEN)
@@ -50,7 +48,6 @@ export class AuthLocalStrategy extends PassportStrategyFactory<Strategy>(
   /**
    * Validate the user based on the username and password
    * from the request body
-   *
    * @param username - The username to authenticate
    * @param password - The plain text password
    */

diff --git a/packages/nestjs-auth-recovery/src/services/auth-recovery.service.ts b/packages/nestjs-auth-recovery/src/services/auth-recovery.service.ts
@@ -40,7 +40,6 @@ export class AuthRecoveryService implements AuthRecoveryServiceInterface {
 
   /**
    * Recover lost username providing an email and send the username by email.
-   *
    * @param email - user email
    */
   async recoverLogin(
@@ -65,7 +64,6 @@ export class AuthRecoveryService implements AuthRecoveryServiceInterface {
 
   /**
    * Recover lost password providing an email and send the passcode token by email.
-   *
    * @param email - user email
    */
   async recoverPassword(
@@ -107,7 +105,6 @@ export class AuthRecoveryService implements AuthRecoveryServiceInterface {
 
   /**
    * Validate passcode and return it's user.
-   *
    * @param passcode - user's passcode
    * @param deleteIfValid - flag to delete if valid or not
    */
@@ -130,7 +127,6 @@ export class AuthRecoveryService implements AuthRecoveryServiceInterface {
 
   /**
    * Change user's password by providing it's OTP passcode and the new password.
-   *
    * @param passcode - OTP user's passcode
    * @param newPassword - new user password
    */
@@ -184,7 +180,6 @@ export class AuthRecoveryService implements AuthRecoveryServiceInterface {
 
   /**
    * Recover lost password providing an email and send the passcode token by email.
-   *
    * @param email - user email
    */
   async revokeAllUserPasswordRecoveries(

diff --git a/packages/nestjs-auth-refresh/src/auth-refresh.strategy.ts b/packages/nestjs-auth-refresh/src/auth-refresh.strategy.ts
@@ -43,7 +43,6 @@ export class AuthRefreshStrategy extends PassportStrategyFactory<JwtStrategy>(
 
   /**
    * Validate the user sub from the verified token
-   *
    * @param payload - Authorization payload
    */
   async validate(

diff --git a/packages/nestjs-authentication/src/services/issue-token.service.ts b/packages/nestjs-authentication/src/services/issue-token.service.ts
@@ -25,8 +25,7 @@ export class IssueTokenService implements IssueTokenServiceInterface {
 
   /**
    * Generate the response payload.
-   *
-   * @param identifier - user id or name for `sub` claim
+   * @param id - user id or name for `sub` claim
    */
   async responsePayload(
     id: ReferenceId,

diff --git a/packages/nestjs-authentication/src/services/verify-token.service.ts b/packages/nestjs-authentication/src/services/verify-token.service.ts
@@ -56,7 +56,6 @@ export class VerifyTokenService implements VerifyTokenServiceInterface {
    * Further validate the authenticity of a token.
    *
    * For example, You may want to check if it's id exists in a database or some other source.
-   *
    * @param payload - Payload object
    */
   private async validateToken(

diff --git a/packages/nestjs-cache/src/controllers/cache-crud.controller.ts b/packages/nestjs-cache/src/controllers/cache-crud.controller.ts
@@ -69,8 +69,9 @@ export class CacheCrudController
 {
   /**
    * Constructor.
-   *
+   * @param settings - cache settings
    * @param allCrudServices - instances of all crud services
+   * @param cacheService - instance of cache service
    */
   constructor(
     @Inject(CACHE_MODULE_SETTINGS_TOKEN)
@@ -82,7 +83,6 @@ export class CacheCrudController
 
   /**
    * Get many
-   *
    * @param crudRequest - the CRUD request object
    * @param assignment - the assignment
    */
@@ -97,7 +97,6 @@ export class CacheCrudController
 
   /**
    * Get one
-   *
    * @param crudRequest - the CRUD request object
    * @param assignment - The cache assignment
    */
@@ -112,7 +111,6 @@ export class CacheCrudController
 
   /**
    * Create one
-   *
    * @param crudRequest - the CRUD request object
    * @param cacheCreateDto - cache create dto
    * @param assignment - The cache assignment
@@ -161,7 +159,6 @@ export class CacheCrudController
 
   /**
    * Create one
-   *
    * @param crudRequest - the CRUD request object
    * @param cacheUpdateDto - cache create dto
    * @param assignment - The cache assignment
@@ -186,7 +183,6 @@ export class CacheCrudController
 
   /**
    * Delete one
-   *
    * @param crudRequest - the CRUD request object
    * @param assignment - The cache assignment
    */
@@ -201,7 +197,6 @@ export class CacheCrudController
 
   /**
    * Get the crud service for the given assignment.
-   *
    * @internal
    * @param assignment - The cache assignment
    */
@@ -219,7 +214,6 @@ export class CacheCrudController
 
   /**
    * Get the entity key for the given assignment.
-   *
    * @param assignment - The cache assignment
    */
   protected getEntityKey(assignment: ReferenceAssignment): string {

diff --git a/packages/nestjs-cache/src/services/cache-crud.service.ts b/packages/nestjs-cache/src/services/cache-crud.service.ts
@@ -10,7 +10,6 @@ import { CacheInterface } from '@concepta/ts-common';
 export class CacheCrudService extends TypeOrmCrudService<CacheInterface> {
   /**
    * Constructor
-   *
    * @param repo - instance of the cache repository.
    */
   constructor(repo: Repository<CacheInterface>) {

diff --git a/packages/nestjs-cache/src/services/cache.service.ts b/packages/nestjs-cache/src/services/cache.service.ts
@@ -34,7 +34,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Create a cache with a for the given assignee.
-   *
    * @param assignment - The cache assignment
    * @param cache - The data to create
    */
@@ -119,7 +118,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Delete a cache based on params
-   *
    * @param assignment - The cache assignment
    * @param cache - The cache to delete
    */
@@ -138,7 +136,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Get all CACHEs for assignee.
-   *
    * @param assignment - The assignment of the check
    * @param cache - The cache to get assignments
    */
@@ -189,7 +186,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Clear all caches for a given assignee.
-   *
    * @param assignment - The assignment of the repository
    * @param cache - The cache to clear
    */
@@ -216,7 +212,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Delete CACHE based on assignment
-   *
    * @internal
    * @param assignment - The assignment to delete id from
    * @param id - The id or ids to delete
@@ -292,7 +287,6 @@ export class CacheService implements CacheServiceInterface {
 
   /**
    * Get the assignment repo for the given assignment.
-   *
    * @internal
    * @param assignment - The cache assignment
    */
-Original file line number
+Diff line change
@@ Expand Up @@
     /**
      * Define access control grants required for this route.
-     *
      * @param acGrants - Array of access control grants.
      * @returns Decorator function.
      */
@@ Expand Down @@