From afc003b20097712625ffd053e256ef5336e27b6e Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Fri, 7 Apr 2023 14:49:45 +0200 Subject: [PATCH] docs: fix typedoc generation with inheritance MIME-Version: 1.0 Content-Type: text/plain; charset=utf8 Content-Transfer-Encoding: 8bit Signed-off-by: Jérôme Benoit --- .eslintrc.js | 2 +- src/pools/abstract-pool.ts | 25 +++++++++++-------- src/pools/cluster/dynamic.ts | 6 ++--- src/pools/cluster/fixed.ts | 20 +++++++-------- .../abstract-worker-choice-strategy.ts | 10 ++++---- .../fair-share-worker-choice-strategy.ts | 8 +++--- .../less-busy-worker-choice-strategy.ts | 8 +++--- .../less-used-worker-choice-strategy.ts | 6 ++--- .../round-robin-worker-choice-strategy.ts | 6 ++--- ...hted-round-robin-worker-choice-strategy.ts | 8 +++--- src/pools/thread/dynamic.ts | 6 ++--- src/pools/thread/fixed.ts | 18 ++++++------- src/worker/cluster-worker.ts | 4 +-- src/worker/thread-worker.ts | 2 +- 14 files changed, 66 insertions(+), 63 deletions(-) diff --git a/.eslintrc.js b/.eslintrc.js index 09870255..4fc34807 100644 --- a/.eslintrc.js +++ b/.eslintrc.js @@ -93,7 +93,7 @@ module.exports = defineConfig({ 'error', { ignoreProperties: true } ], - 'tsdoc/syntax': 'error' + 'tsdoc/syntax': 'warn' } }, { diff --git a/src/pools/abstract-pool.ts b/src/pools/abstract-pool.ts index ad21effb..68e83371 100644 --- a/src/pools/abstract-pool.ts +++ b/src/pools/abstract-pool.ts @@ -25,10 +25,10 @@ export abstract class AbstractPool< Data = unknown, Response = unknown > implements IPoolInternal { - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly workers: Array> = [] - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly emitter?: PoolEmitter /** @@ -154,7 +154,7 @@ export abstract class AbstractPool< this.opts.enableEvents = opts.enableEvents ?? true } - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract get type (): PoolType /** @@ -174,7 +174,7 @@ export abstract class AbstractPool< return this.workers.findIndex(workerItem => workerItem.worker === worker) } - /** {@inheritDoc} */ + /** @inheritDoc */ public setWorkerChoiceStrategy ( workerChoiceStrategy: WorkerChoiceStrategy ): void { @@ -193,10 +193,10 @@ export abstract class AbstractPool< ) } - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract get full (): boolean - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract get busy (): boolean protected internalBusy (): boolean { @@ -206,14 +206,14 @@ export abstract class AbstractPool< ) } - /** {@inheritDoc} */ + /** @inheritDoc */ public findFreeWorkerKey (): number { return this.workers.findIndex(workerItem => { return workerItem.tasksUsage.running === 0 }) } - /** {@inheritDoc} */ + /** @inheritDoc */ public async execute (data: Data): Promise { const [workerKey, worker] = this.chooseWorker() const messageId = crypto.randomUUID() @@ -229,7 +229,7 @@ export abstract class AbstractPool< return res } - /** {@inheritDoc} */ + /** @inheritDoc */ public async destroy (): Promise { await Promise.all( this.workers.map(async workerItem => { @@ -239,7 +239,7 @@ export abstract class AbstractPool< } /** - * Shutdowns given worker. + * Shutdowns given worker in the pool. * * @param worker - A worker within `workers`. */ @@ -248,6 +248,8 @@ export abstract class AbstractPool< /** * Setup hook that can be overridden by a Poolifier pool implementation * to run code before workers are created in the abstract constructor. + * + * @virtual */ protected setupHook (): void { // Can be overridden @@ -341,6 +343,7 @@ export abstract class AbstractPool< * Can be used to update the `maxListeners` or binding the `main-worker`\<-\>`worker` connection if not bind by default. * * @param worker - The newly created worker. + * @virtual */ protected abstract afterWorkerSetup (worker: Worker): void @@ -423,7 +426,7 @@ export abstract class AbstractPool< } /** - * Gets worker tasks usage. + * Gets the given worker tasks usage in the pool. * * @param worker - The worker. * @returns The worker tasks usage. diff --git a/src/pools/cluster/dynamic.ts b/src/pools/cluster/dynamic.ts index 79f684cb..6171ce4e 100644 --- a/src/pools/cluster/dynamic.ts +++ b/src/pools/cluster/dynamic.ts @@ -34,17 +34,17 @@ export class DynamicClusterPool< super(min, filePath, opts) } - /** {@inheritDoc} */ + /** @inheritDoc */ public get type (): PoolType { return PoolType.DYNAMIC } - /** {@inheritDoc} */ + /** @inheritDoc */ public get full (): boolean { return this.workers.length === this.max } - /** {@inheritDoc} */ + /** @inheritDoc */ public get busy (): boolean { return this.full && this.findFreeWorkerKey() === -1 } diff --git a/src/pools/cluster/fixed.ts b/src/pools/cluster/fixed.ts index d644f229..78de7073 100644 --- a/src/pools/cluster/fixed.ts +++ b/src/pools/cluster/fixed.ts @@ -55,28 +55,28 @@ export class FixedClusterPool< super(numberOfWorkers, filePath, opts) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected setupHook (): void { cluster.setupPrimary({ ...this.opts.settings, exec: this.filePath }) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected isMain (): boolean { return cluster.isPrimary } - /** {@inheritDoc} */ + /** @inheritDoc */ public destroyWorker (worker: Worker): void { this.sendToWorker(worker, { kill: 1 }) worker.kill() } - /** {@inheritDoc} */ + /** @inheritDoc */ protected sendToWorker (worker: Worker, message: MessageValue): void { worker.send(message) } - /** {@inheritDoc} */ + /** @inheritDoc */ public registerWorkerMessageListener( worker: Worker, listener: (message: MessageValue) => void @@ -84,28 +84,28 @@ export class FixedClusterPool< worker.on('message', listener) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected createWorker (): Worker { return cluster.fork(this.opts.env) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected afterWorkerSetup (worker: Worker): void { // Listen to worker messages. this.registerWorkerMessageListener(worker, super.workerListener()) } - /** {@inheritDoc} */ + /** @inheritDoc */ public get type (): PoolType { return PoolType.FIXED } - /** {@inheritDoc} */ + /** @inheritDoc */ public get full (): boolean { return this.workers.length === this.numberOfWorkers } - /** {@inheritDoc} */ + /** @inheritDoc */ public get busy (): boolean { return this.internalBusy() } diff --git a/src/pools/selection-strategies/abstract-worker-choice-strategy.ts b/src/pools/selection-strategies/abstract-worker-choice-strategy.ts index 332b3fc1..0d337b53 100644 --- a/src/pools/selection-strategies/abstract-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/abstract-worker-choice-strategy.ts @@ -18,9 +18,9 @@ export abstract class AbstractWorkerChoiceStrategy< Data = unknown, Response = unknown > implements IWorkerChoiceStrategy { - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly isDynamicPool: boolean - /** {@inheritDoc} */ + /** @inheritDoc */ public requiredStatistics: RequiredStatistics = { runTime: false, avgRunTime: false @@ -38,12 +38,12 @@ export abstract class AbstractWorkerChoiceStrategy< this.choose.bind(this) } - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract reset (): boolean - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract choose (): number - /** {@inheritDoc} */ + /** @inheritDoc */ public abstract remove (workerKey: number): boolean } diff --git a/src/pools/selection-strategies/fair-share-worker-choice-strategy.ts b/src/pools/selection-strategies/fair-share-worker-choice-strategy.ts index 60c22a29..f8427d01 100644 --- a/src/pools/selection-strategies/fair-share-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/fair-share-worker-choice-strategy.ts @@ -28,7 +28,7 @@ export class FairShareWorkerChoiceStrategy< > extends AbstractWorkerChoiceStrategy implements IWorkerChoiceStrategy { - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly requiredStatistics: RequiredStatistics = { runTime: true, avgRunTime: true @@ -42,13 +42,13 @@ export class FairShareWorkerChoiceStrategy< WorkerVirtualTaskTimestamp > = new Map() - /** {@inheritDoc} */ + /** @inheritDoc */ public reset (): boolean { this.workerLastVirtualTaskTimestamp.clear() return true } - /** {@inheritDoc} */ + /** @inheritDoc */ public choose (): number { let minWorkerVirtualTaskEndTimestamp = Infinity let chosenWorkerKey!: number @@ -66,7 +66,7 @@ export class FairShareWorkerChoiceStrategy< return chosenWorkerKey } - /** {@inheritDoc} */ + /** @inheritDoc */ public remove (workerKey: number): boolean { const workerDeleted = this.workerLastVirtualTaskTimestamp.delete(workerKey) for (const [key, value] of this.workerLastVirtualTaskTimestamp.entries()) { diff --git a/src/pools/selection-strategies/less-busy-worker-choice-strategy.ts b/src/pools/selection-strategies/less-busy-worker-choice-strategy.ts index 9952a41d..a9c55004 100644 --- a/src/pools/selection-strategies/less-busy-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/less-busy-worker-choice-strategy.ts @@ -19,18 +19,18 @@ export class LessBusyWorkerChoiceStrategy< > extends AbstractWorkerChoiceStrategy implements IWorkerChoiceStrategy { - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly requiredStatistics: RequiredStatistics = { runTime: true, avgRunTime: false } - /** {@inheritDoc} */ + /** @inheritDoc */ public reset (): boolean { return true } - /** {@inheritDoc} */ + /** @inheritDoc */ public choose (): number { const freeWorkerKey = this.pool.findFreeWorkerKey() if (freeWorkerKey !== -1) { @@ -50,7 +50,7 @@ export class LessBusyWorkerChoiceStrategy< return lessBusyWorkerKey } - /** {@inheritDoc} */ + /** @inheritDoc */ public remove (workerKey: number): boolean { return true } diff --git a/src/pools/selection-strategies/less-used-worker-choice-strategy.ts b/src/pools/selection-strategies/less-used-worker-choice-strategy.ts index dffed99e..f3b45e06 100644 --- a/src/pools/selection-strategies/less-used-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/less-used-worker-choice-strategy.ts @@ -16,12 +16,12 @@ export class LessUsedWorkerChoiceStrategy< > extends AbstractWorkerChoiceStrategy implements IWorkerChoiceStrategy { - /** {@inheritDoc} */ + /** @inheritDoc */ public reset (): boolean { return true } - /** {@inheritDoc} */ + /** @inheritDoc */ public choose (): number { const freeWorkerKey = this.pool.findFreeWorkerKey() if (freeWorkerKey !== -1) { @@ -42,7 +42,7 @@ export class LessUsedWorkerChoiceStrategy< return lessUsedWorkerKey } - /** {@inheritDoc} */ + /** @inheritDoc */ public remove (workerKey: number): boolean { return true } diff --git a/src/pools/selection-strategies/round-robin-worker-choice-strategy.ts b/src/pools/selection-strategies/round-robin-worker-choice-strategy.ts index 91ceb5bc..9cc966c4 100644 --- a/src/pools/selection-strategies/round-robin-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/round-robin-worker-choice-strategy.ts @@ -21,13 +21,13 @@ export class RoundRobinWorkerChoiceStrategy< */ private nextWorkerId: number = 0 - /** {@inheritDoc} */ + /** @inheritDoc */ public reset (): boolean { this.nextWorkerId = 0 return true } - /** {@inheritDoc} */ + /** @inheritDoc */ public choose (): number { const chosenWorkerKey = this.nextWorkerId this.nextWorkerId = @@ -37,7 +37,7 @@ export class RoundRobinWorkerChoiceStrategy< return chosenWorkerKey } - /** {@inheritDoc} */ + /** @inheritDoc */ public remove (workerKey: number): boolean { if (this.nextWorkerId === workerKey) { if (this.pool.workers.length === 0) { diff --git a/src/pools/selection-strategies/weighted-round-robin-worker-choice-strategy.ts b/src/pools/selection-strategies/weighted-round-robin-worker-choice-strategy.ts index e1325865..997366cd 100644 --- a/src/pools/selection-strategies/weighted-round-robin-worker-choice-strategy.ts +++ b/src/pools/selection-strategies/weighted-round-robin-worker-choice-strategy.ts @@ -30,7 +30,7 @@ export class WeightedRoundRobinWorkerChoiceStrategy< > extends AbstractWorkerChoiceStrategy implements IWorkerChoiceStrategy { - /** {@inheritDoc} */ + /** @inheritDoc */ public readonly requiredStatistics: RequiredStatistics = { runTime: true, avgRunTime: true @@ -63,7 +63,7 @@ export class WeightedRoundRobinWorkerChoiceStrategy< this.initWorkersTaskRunTime() } - /** {@inheritDoc} */ + /** @inheritDoc */ public reset (): boolean { this.currentWorkerId = 0 this.workersTaskRunTime.clear() @@ -71,7 +71,7 @@ export class WeightedRoundRobinWorkerChoiceStrategy< return true } - /** {@inheritDoc} */ + /** @inheritDoc */ public choose (): number { const chosenWorkerKey = this.currentWorkerId if (this.isDynamicPool && !this.workersTaskRunTime.has(chosenWorkerKey)) { @@ -99,7 +99,7 @@ export class WeightedRoundRobinWorkerChoiceStrategy< return chosenWorkerKey } - /** {@inheritDoc} */ + /** @inheritDoc */ public remove (workerKey: number): boolean { if (this.currentWorkerId === workerKey) { if (this.pool.workers.length === 0) { diff --git a/src/pools/thread/dynamic.ts b/src/pools/thread/dynamic.ts index 33e42892..62ddba9f 100644 --- a/src/pools/thread/dynamic.ts +++ b/src/pools/thread/dynamic.ts @@ -35,17 +35,17 @@ export class DynamicThreadPool< super(min, filePath, opts) } - /** {@inheritDoc} */ + /** @inheritDoc */ public get type (): PoolType { return PoolType.DYNAMIC } - /** {@inheritDoc} */ + /** @inheritDoc */ public get full (): boolean { return this.workers.length === this.max } - /** {@inheritDoc} */ + /** @inheritDoc */ public get busy (): boolean { return this.full && this.findFreeWorkerKey() === -1 } diff --git a/src/pools/thread/fixed.ts b/src/pools/thread/fixed.ts index 2c4f66f0..a95a8603 100644 --- a/src/pools/thread/fixed.ts +++ b/src/pools/thread/fixed.ts @@ -45,12 +45,12 @@ export class FixedThreadPool< super(numberOfThreads, filePath, opts) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected isMain (): boolean { return isMainThread } - /** {@inheritDoc} */ + /** @inheritDoc */ public async destroyWorker ( worker: ThreadWorkerWithMessageChannel ): Promise { @@ -58,7 +58,7 @@ export class FixedThreadPool< await worker.terminate() } - /** {@inheritDoc} */ + /** @inheritDoc */ protected sendToWorker ( worker: ThreadWorkerWithMessageChannel, message: MessageValue @@ -66,7 +66,7 @@ export class FixedThreadPool< worker.postMessage(message) } - /** {@inheritDoc} */ + /** @inheritDoc */ public registerWorkerMessageListener( messageChannel: ThreadWorkerWithMessageChannel, listener: (message: MessageValue) => void @@ -74,14 +74,14 @@ export class FixedThreadPool< messageChannel.port2?.on('message', listener) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected createWorker (): ThreadWorkerWithMessageChannel { return new Worker(this.filePath, { env: SHARE_ENV }) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected afterWorkerSetup (worker: ThreadWorkerWithMessageChannel): void { const { port1, port2 } = new MessageChannel() worker.postMessage({ parent: port1 }, [port1]) @@ -91,17 +91,17 @@ export class FixedThreadPool< this.registerWorkerMessageListener(worker, super.workerListener()) } - /** {@inheritDoc} */ + /** @inheritDoc */ public get type (): PoolType { return PoolType.FIXED } - /** {@inheritDoc} */ + /** @inheritDoc */ public get full (): boolean { return this.workers.length === this.numberOfWorkers } - /** {@inheritDoc} */ + /** @inheritDoc */ public get busy (): boolean { return this.internalBusy() } diff --git a/src/worker/cluster-worker.ts b/src/worker/cluster-worker.ts index 43e86dd7..655520cc 100644 --- a/src/worker/cluster-worker.ts +++ b/src/worker/cluster-worker.ts @@ -38,12 +38,12 @@ export class ClusterWorker< ) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected sendToMainWorker (message: MessageValue): void { this.getMainWorker().send(message) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected handleError (e: Error | string): string { return e instanceof Error ? e.message : e } diff --git a/src/worker/thread-worker.ts b/src/worker/thread-worker.ts index 639fd19c..ac775a09 100644 --- a/src/worker/thread-worker.ts +++ b/src/worker/thread-worker.ts @@ -32,7 +32,7 @@ export class ThreadWorker< super('worker-thread-pool:poolifier', isMainThread, fn, parentPort, opts) } - /** {@inheritDoc} */ + /** @inheritDoc */ protected sendToMainWorker (message: MessageValue): void { this.getMainWorker().postMessage(message) } -- 2.34.1