From 3832ad95c98b136ef703a29685fedebe4a5e3ba2 Mon Sep 17 00:00:00 2001 From: Shinigami Date: Wed, 17 Feb 2021 08:58:12 +0100 Subject: [PATCH] Improve jsdoc comments (#175) * Improve jsdoc comments * Update eslint-plugin-jsdoc --- .eslintrc.js | 40 ++++++++++++++++++++++++++++++++++++-- README.md | 16 +++++++-------- package-lock.json | 6 +++--- package.json | 2 +- src/pools/abstract-pool.ts | 35 +++++++++++++++++++++++++++++++++ src/utility-types.ts | 2 +- 6 files changed, 86 insertions(+), 15 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 6c8063c8..c3c51fe7 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -51,10 +51,11 @@ module.exports = { { skipWords: [ 'poolifier', - 'pioardi', 'christopher', 'ecma', + 'enum', 'jsdoc', + 'pioardi', 'readonly', 'serializable', 'unregister', @@ -69,7 +70,37 @@ module.exports = { files: ['src/**/*.ts'], extends: 'plugin:jsdoc/recommended', rules: { + 'jsdoc/match-description': [ + 'warn', + { + mainDescription: + '/^[A-Z`].+?(\\.|:)(\\n\\n.*((\\n{1,2}- .+)|(_.+_)|`.+`|\\n\\n---))?$/us', + matchDescription: '^[A-Z`].+(\\.|`.+`)$', + contexts: ['any'], + tags: { + param: true, + returns: true + } + } + ], 'jsdoc/no-types': 'error', + 'jsdoc/require-jsdoc': [ + 'warn', + { + contexts: [ + 'ClassDeclaration', + 'ClassProperty:not([accessibility=/(private|protected)/])', + 'ExportNamedDeclaration:has(VariableDeclaration)', + 'FunctionExpression', + 'MethodDefinition:not([accessibility=/(private|protected)/]) > FunctionExpression', + 'TSEnumDeclaration', + 'TSInterfaceDeclaration', + 'TSMethodSignature', + // 'TSPropertySignature', + 'TSTypeAliasDeclaration' + ] + } + ], 'jsdoc/require-param-type': 'off', 'jsdoc/require-returns-type': 'off' } @@ -94,5 +125,10 @@ module.exports = { 'node/no-missing-require': 'off' } } - ] + ], + settings: { + jsdoc: { + mode: 'typescript' + } + } } diff --git a/README.md b/README.md index ad01a6ee..fa9cd83a 100644 --- a/README.md +++ b/README.md @@ -175,17 +175,17 @@ This method will call the terminate method on each worker. `opts` (optional) An object with these properties: - `maxInactiveTime` - Max time to wait tasks to work on (in ms), after this period the new worker threads will die. -The last active time of your worker unit will be updated when a task is submitted to a worker or when a worker terminate a task. -If `killBehavior` is set to `KillBehaviors.HARD` this value represents also the timeout for the tasks that you submit to the pool, when this timeout expires your tasks is interrupted and the worker is killed if is not part of the minimum size of the pool. -If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed. -Default: 60.000 ms + The last active time of your worker unit will be updated when a task is submitted to a worker or when a worker terminate a task. + If `killBehavior` is set to `KillBehaviors.HARD` this value represents also the timeout for the tasks that you submit to the pool, when this timeout expires your tasks is interrupted and the worker is killed if is not part of the minimum size of the pool. + If `killBehavior` is set to `KillBehaviors.SOFT` your tasks have no timeout and your workers will not be terminated until your task is completed. + Default: 60.000 ms - `async` - true/false, true if your function contains async pieces else false - `killBehavior` - Dictates if your async unit (worker/process) will be deleted in case that a task is active on it. -**SOFT**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker **wont** be deleted. -**HARD**: If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted. -This option only apply to the newly created workers. -Default: `SOFT` + **SOFT**: If `currentTime - lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker **wont** be deleted. + **HARD**: If `lastActiveTime` is greater than `maxInactiveTime` but a task is still running, then the worker will be deleted. + This option only apply to the newly created workers. + Default: `SOFT` ## Choose your pool diff --git a/package-lock.json b/package-lock.json index cab635a4..c7bcf203 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1618,9 +1618,9 @@ } }, "eslint-plugin-jsdoc": { - "version": "32.0.1", - "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-32.0.1.tgz", - "integrity": "sha512-7T6cKNGJsJ1SxhG4vbEBi2fRmUL3DHzRNsiQZri4vkgIQjCoBb40ZNxSNwBqiVz16C7tW3qLncPoNXsiIFdzcg==", + "version": "32.0.2", + "resolved": "https://registry.npmjs.org/eslint-plugin-jsdoc/-/eslint-plugin-jsdoc-32.0.2.tgz", + "integrity": "sha512-zMAJAsq02uWVGrmr6TVlJ2nue0wM/94loWb+0Z/aJcX+oELIet+Z1vtSU9xoSkPaOJE1tpI6CkHgUZfVLKTaJg==", "dev": true, "requires": { "comment-parser": "1.1.2", diff --git a/package.json b/package.json index daf3df0e..22e5a630 100644 --- a/package.json +++ b/package.json @@ -62,7 +62,7 @@ "eslint": "^7.20.0", "eslint-config-standard": "^16.0.2", "eslint-plugin-import": "^2.22.1", - "eslint-plugin-jsdoc": "^32.0.1", + "eslint-plugin-jsdoc": "^32.0.2", "eslint-plugin-node": "^11.1.0", "eslint-plugin-prettierx": "^0.17.1", "eslint-plugin-promise": "^4.3.1", diff --git a/src/pools/abstract-pool.ts b/src/pools/abstract-pool.ts index 0685f998..5ef2eed9 100644 --- a/src/pools/abstract-pool.ts +++ b/src/pools/abstract-pool.ts @@ -21,9 +21,33 @@ export type ExitHandler = (this: Worker, code: number) => void * Basic interface that describes the minimum required implementation of listener events for a pool-worker. */ export interface IWorker { + /** + * Register a listener to the error event. + * + * @param event `'error'`. + * @param handler The error handler. + */ on(event: 'error', handler: ErrorHandler): void + /** + * Register a listener to the online event. + * + * @param event `'online'`. + * @param handler The online handler. + */ on(event: 'online', handler: OnlineHandler): void + /** + * Register a listener to the exit event. + * + * @param event `'exit'`. + * @param handler The exit handler. + */ on(event: 'exit', handler: ExitHandler): void + /** + * Register a listener to the exit event that will only performed once. + * + * @param event `'exit'`. + * @param handler The exit handler. + */ once(event: 'exit', handler: ExitHandler): void } @@ -82,6 +106,8 @@ export abstract class AbstractPool< public nextWorkerIndex: number = 0 /** + * The tasks map. + * * - `key`: The `Worker` * - `value`: Number of tasks currently in progress on the worker. */ @@ -150,6 +176,12 @@ export abstract class AbstractPool< return this.nextWorkerIndex } + /** + * Perform the task specified in the constructor with the data parameter. + * + * @param data The input for the specified task. + * @returns Promise that will be resolved when the task is successfully completed. + */ public execute (data: Data): Promise { // Configure worker to handle message with the specified task const worker = this.chooseWorker() @@ -160,6 +192,9 @@ export abstract class AbstractPool< return res } + /** + * Shut down every current worker in this pool. + */ public async destroy (): Promise { await Promise.all(this.workers.map(worker => this.destroyWorker(worker))) } diff --git a/src/utility-types.ts b/src/utility-types.ts index d680fa16..7ea86042 100644 --- a/src/utility-types.ts +++ b/src/utility-types.ts @@ -3,7 +3,7 @@ import type { MessagePort } from 'worker_threads' import type { KillBehavior } from './worker/worker-options' /** - * Make all properties in T non-readonly + * Make all properties in T non-readonly. */ export type Draft = { -readonly [P in keyof T]?: T[P] } -- 2.34.1