From e4f88381973f4ff7d8a32523906662dc819e227b Mon Sep 17 00:00:00 2001 From: =?utf8?q?J=C3=A9r=C3=B4me=20Benoit?= Date: Tue, 24 Mar 2026 17:54:43 +0100 Subject: [PATCH] docs: harmonize JSDoc @param/@returns across entire codebase - Add missing dash separator to @param tags in OCPP20VariableRegistry and OCPPServiceUtils (35 occurrences) - Fill empty @param descriptions in Helpers, IdTagsCache, OCPPRequestService, and Worker modules (23 occurrences) - Replace type-only @returns with meaningful descriptions --- src/charging-station/Helpers.ts | 16 +++---- src/charging-station/IdTagsCache.ts | 12 ++--- .../ocpp/2.0/OCPP20VariableRegistry.ts | 48 +++++++++---------- .../ocpp/OCPPRequestService.ts | 8 ++-- src/charging-station/ocpp/OCPPServiceUtils.ts | 42 ++++++++-------- src/worker/WorkerAbstract.ts | 6 +-- src/worker/WorkerDynamicPool.ts | 4 +- src/worker/WorkerFixedPool.ts | 4 +- src/worker/WorkerSet.ts | 4 +- 9 files changed, 72 insertions(+), 72 deletions(-) diff --git a/src/charging-station/Helpers.ts b/src/charging-station/Helpers.ts index 36f3ff68..3056a7bb 100644 --- a/src/charging-station/Helpers.ts +++ b/src/charging-station/Helpers.ts @@ -805,7 +805,7 @@ export const getChargingStationChargingProfilesLimit = ( * and sorted by priorities * @param chargingStation - Charging station * @param connectorId - Connector id - * @returns connector charging profiles array + * @returns Connector charging profiles array */ export const getConnectorChargingProfiles = ( chargingStation: ChargingStation, @@ -1069,9 +1069,9 @@ const getSingleChargingSchedule = ( /** * Get the charging profiles limit for a connector * Charging profiles shall already be sorted by priorities - * @param chargingStation - - * @param connectorId - - * @param chargingProfiles - + * @param chargingStation - The charging station instance + * @param connectorId - The connector identifier + * @param chargingProfiles - Array of charging profiles * @returns ChargingProfilesLimit */ const getChargingProfilesLimit = ( @@ -1366,10 +1366,10 @@ const canProceedRecurringChargingProfile = ( /** * Adjust recurring charging profile startSchedule to the current recurrency time interval if needed - * @param chargingProfile - - * @param currentDate - - * @param logPrefix - - * @returns boolean + * @param chargingProfile - The charging profile to adjust + * @param currentDate - The current date/time + * @param logPrefix - Prefix for logging messages + * @returns Whether the charging profile is active at the given date */ const prepareRecurringChargingProfile = ( chargingProfile: ChargingProfile, diff --git a/src/charging-station/IdTagsCache.ts b/src/charging-station/IdTagsCache.ts index a73dcfa9..166280c8 100644 --- a/src/charging-station/IdTagsCache.ts +++ b/src/charging-station/IdTagsCache.ts @@ -41,10 +41,10 @@ export class IdTagsCache { /** * Gets one idtag from the cache given the distribution * Must be called after checking the cache is not an empty array - * @param distribution - - * @param chargingStation - - * @param connectorId - - * @returns string + * @param distribution - The distribution strategy for selecting an idtag + * @param chargingStation - The charging station instance + * @param connectorId - The connector identifier + * @returns Selected idtag string */ public getIdTag ( distribution: IdTagDistribution, @@ -71,8 +71,8 @@ export class IdTagsCache { /** * Gets all idtags from the cache * Must be called after checking the cache is not an empty array - * @param file - - * @returns string[] | undefined + * @param file - The idtags file path + * @returns Array of idtag strings or undefined if not cached */ public getIdTags (file: string): string[] | undefined { if (!this.hasIdTagsCache(file)) { diff --git a/src/charging-station/ocpp/2.0/OCPP20VariableRegistry.ts b/src/charging-station/ocpp/2.0/OCPP20VariableRegistry.ts index 470ef54d..da809ee3 100644 --- a/src/charging-station/ocpp/2.0/OCPP20VariableRegistry.ts +++ b/src/charging-station/ocpp/2.0/OCPP20VariableRegistry.ts @@ -91,9 +91,9 @@ export interface VariableMetadata { * 2. Case-insensitive composite key (lookup convenience): `${component}[.].${variable}` all lower case * - Built with buildCaseInsensitiveCompositeKey(). * Rationale: Maintain original case for canonical metadata storage while offering tolerant lookups. - * @param component Component name. - * @param variable Variable name. - * @param instance Optional instance qualifier. + * @param component - Component name. + * @param variable - Variable name. + * @param instance - Optional instance qualifier. * @returns Primary registry key string. */ function buildRegistryKey (component: string, variable: string, instance?: string): string { @@ -2375,9 +2375,9 @@ export const VARIABLE_REGISTRY: Record = { /** * Build composite lookup key (lower-cased) including optional instance. * Format: `component[.instance].variable` all lower case. - * @param component Component name. - * @param instance Optional instance qualifier. - * @param variable Variable name. + * @param component - Component name. + * @param instance - Optional instance qualifier. + * @param variable - Variable name. * @returns Lower-case composite key for lookup. */ export function buildCaseInsensitiveCompositeKey ( @@ -2398,9 +2398,9 @@ const VARIABLE_REGISTRY_LOOKUP_CI: Record = Object.val /** * Apply optional metadata post-processing to a resolved variable value. - * @param chargingStation Charging station context. - * @param variableMetadata Variable metadata entry. - * @param value Resolved raw value. + * @param chargingStation - Charging station context. + * @param variableMetadata - Variable metadata entry. + * @param value - Resolved raw value. * @returns Post-processed value (or original when no postProcess defined). */ export function applyPostProcess ( @@ -2416,8 +2416,8 @@ export function applyPostProcess ( /** * Enforce reporting/value size limit on a string. - * @param value Incoming value string. - * @param sizeLimitRaw Raw size limit value (string form). + * @param value - Incoming value string. + * @param sizeLimitRaw - Raw size limit value (string form). * @returns Possibly truncated value respecting size limit. */ export function enforceReportingValueSize (value: string, sizeLimitRaw: string): string { @@ -2430,9 +2430,9 @@ export function enforceReportingValueSize (value: string, sizeLimitRaw: string): /** * Retrieve variable metadata with case-insensitive fallback. - * @param component Component name. - * @param variable Variable name. - * @param instance Optional instance qualifier. + * @param component - Component name. + * @param variable - Variable name. + * @param instance - Optional instance qualifier. * @returns Matching variable metadata or undefined. */ export function getVariableMetadata ( @@ -2459,7 +2459,7 @@ export function getVariableMetadata ( /** * Check if variable metadata is persistent. - * @param variableMetadata Variable metadata entry. + * @param variableMetadata - Variable metadata entry. * @returns True when persistence is Persistent. */ export function isPersistent (variableMetadata: VariableMetadata): boolean { @@ -2468,7 +2468,7 @@ export function isPersistent (variableMetadata: VariableMetadata): boolean { /** * Check if variable metadata is read-only. - * @param variableMetadata Variable metadata entry. + * @param variableMetadata - Variable metadata entry. * @returns True when mutability is ReadOnly. */ export function isReadOnly (variableMetadata: VariableMetadata): boolean { @@ -2477,7 +2477,7 @@ export function isReadOnly (variableMetadata: VariableMetadata): boolean { /** * Check if variable metadata is write-only. - * @param variableMetadata Variable metadata entry. + * @param variableMetadata - Variable metadata entry. * @returns True when mutability is WriteOnly. */ export function isWriteOnly (variableMetadata: VariableMetadata): boolean { @@ -2486,8 +2486,8 @@ export function isWriteOnly (variableMetadata: VariableMetadata): boolean { /** * Resolve variable value using dynamicValueResolver if present else defaultValue. - * @param chargingStation Charging station context. - * @param variableMetadata Variable metadata entry. + * @param chargingStation - Charging station context. + * @param variableMetadata - Variable metadata entry. * @returns Resolved value string (empty when no default). */ export function resolveValue ( @@ -2503,8 +2503,8 @@ export function resolveValue ( /** * Validate raw value against variable metadata constraints. * Performs length, datatype specific and enumeration checks. - * @param variableMetadata Variable metadata entry. - * @param rawValue Raw value string to validate. + * @param variableMetadata - Variable metadata entry. + * @param rawValue - Raw value string to validate. * @returns Validation result with ok flag and optional reason/info. */ export function validateValue ( @@ -2721,7 +2721,7 @@ export function validateValue ( /** * Validate URL using generic parsing (any scheme accepted). - * @param value Raw URL string. + * @param value - Raw URL string. * @returns Validation result with ok flag and optional reason/info. */ function validateGenericUrl (value: string): { @@ -2737,8 +2737,8 @@ function validateGenericUrl (value: string): { /** * Validate URL scheme against an allowed list after generic format check. - * @param value Raw URL string. - * @param allowedSchemes Allowed protocol schemes (with trailing colon). + * @param value - Raw URL string. + * @param allowedSchemes - Allowed protocol schemes (with trailing colon). * @returns Validation result with ok flag and optional reason/info. */ function validateUrlScheme ( diff --git a/src/charging-station/ocpp/OCPPRequestService.ts b/src/charging-station/ocpp/OCPPRequestService.ts index 3a39a373..a365828c 100644 --- a/src/charging-station/ocpp/OCPPRequestService.ts +++ b/src/charging-station/ocpp/OCPPRequestService.ts @@ -345,8 +345,8 @@ export abstract class OCPPRequestService { return await new Promise((resolve, reject: (reason?: unknown) => void) => { /** * Function that will receive the request's response - * @param payload - - * @param requestPayload - + * @param payload - The response payload + * @param requestPayload - The original request payload */ const responseCallback = (payload: JsonType, requestPayload: JsonType): void => { if (chargingStation.stationInfo?.enableStatistics === true) { @@ -376,8 +376,8 @@ export abstract class OCPPRequestService { /** * Function that will receive the request's error response - * @param ocppError - - * @param requestStatistic - + * @param ocppError - The OCPP error response + * @param requestStatistic - Whether to record request statistics */ const errorCallback = (ocppError: OCPPError, requestStatistic = true): void => { if (requestStatistic && chargingStation.stationInfo?.enableStatistics === true) { diff --git a/src/charging-station/ocpp/OCPPServiceUtils.ts b/src/charging-station/ocpp/OCPPServiceUtils.ts index 2b7b1304..f502a879 100644 --- a/src/charging-station/ocpp/OCPPServiceUtils.ts +++ b/src/charging-station/ocpp/OCPPServiceUtils.ts @@ -2115,11 +2115,11 @@ const getSampledValueTemplate = ( /** * Builds a sampled value object according to the specified OCPP version. - * @param ocppVersion The OCPP version to use for formatting the sampled value - * @param sampledValueTemplate Template containing measurement configuration and metadata - * @param value The measured numeric value to be included in the sampled value - * @param context Optional context specifying when the measurement was taken (e.g., Sample.Periodic) - * @param phase Optional phase information for multi-phase electrical measurements + * @param ocppVersion - The OCPP version to use for formatting the sampled value + * @param sampledValueTemplate - Template containing measurement configuration and metadata + * @param value - The measured numeric value to be included in the sampled value + * @param context - Optional context specifying when the measurement was taken (e.g., Sample.Periodic) + * @param phase - Optional phase information for multi-phase electrical measurements * @returns A sampled value object formatted according to the specified OCPP version */ function buildSampledValue ( @@ -2380,13 +2380,13 @@ export class OCPPServiceUtils { /** * Creates a Map of compiled OCPP payload validators from configurations. * Reduces code duplication across OCPP services. - * @param configs Array of tuples containing command and validator configuration - * @param options Factory options including OCPP version, schema directory, etc. - * @param options.ocppVersion The OCPP version for schema validation - * @param options.schemaDir Directory path containing JSON schemas - * @param options.moduleName Name of the module for logging - * @param options.methodName Name of the method for logging - * @param ajvInstance Configured Ajv instance for validation + * @param configs - Array of tuples containing command and validator configuration + * @param options - Factory options including OCPP version, schema directory, etc. + * @param options.ocppVersion - The OCPP version for schema validation + * @param options.schemaDir - Directory path containing JSON schemas + * @param options.moduleName - Name of the module for logging + * @param options.methodName - Name of the method for logging + * @param ajvInstance - Configured Ajv instance for validation * @returns Map of commands to their compiled validation functions */ public static createPayloadValidatorMap( @@ -2491,7 +2491,7 @@ export class OCPPServiceUtils { /** * Configuration for a single payload validator. - * @param schemaPath Path to the JSON schema file + * @param schemaPath - Path to the JSON schema file * @returns Configuration object for payload validator creation */ public static readonly PayloadValidatorConfig = (schemaPath: string) => @@ -2501,10 +2501,10 @@ export class OCPPServiceUtils { /** * Options for payload validator creation. - * @param ocppVersion The OCPP version - * @param schemaDir Directory containing JSON schemas - * @param moduleName Name of the OCPP module - * @param methodName Name of the method/command + * @param ocppVersion - The OCPP version + * @param schemaDir - Directory containing JSON schemas + * @param moduleName - Name of the OCPP module + * @param methodName - Name of the method/command * @returns Options object for payload validator creation */ public static readonly PayloadValidatorOptions = ( @@ -2523,10 +2523,10 @@ export class OCPPServiceUtils { /** * Parses and loads a JSON schema file for OCPP payload validation. * Handles file reading and JSON parsing for schema validation. - * @param relativePath Path to the schema file relative to the OCPP utils directory - * @param ocppVersion The OCPP version for error logging context - * @param moduleName Optional module name for error logging - * @param methodName Optional method name for error logging + * @param relativePath - Path to the schema file relative to the OCPP utils directory + * @param ocppVersion - The OCPP version for error logging context + * @param moduleName - Optional module name for error logging + * @param methodName - Optional method name for error logging * @returns Parsed JSON schema object * @throws {NodeJS.ErrnoException} If the schema file cannot be read or parsed */ diff --git a/src/worker/WorkerAbstract.ts b/src/worker/WorkerAbstract.ts index a38db441..c63af4f4 100644 --- a/src/worker/WorkerAbstract.ts +++ b/src/worker/WorkerAbstract.ts @@ -16,8 +16,8 @@ export abstract class WorkerAbstract /** * `WorkerAbstract` constructor. - * @param workerScript - - * @param workerOptions - + * @param workerScript - Path to the worker script file + * @param workerOptions - Worker configuration options */ constructor (workerScript: string | undefined, workerOptions: WorkerOptions) { if (workerScript == null) { @@ -42,7 +42,7 @@ export abstract class WorkerAbstract /** * Adds a task element to the worker pool/set. - * @param elementData - + * @param elementData - The element data to process */ public abstract addElement (elementData: D): Promise /** diff --git a/src/worker/WorkerDynamicPool.ts b/src/worker/WorkerDynamicPool.ts index f7ed91b1..66febb57 100644 --- a/src/worker/WorkerDynamicPool.ts +++ b/src/worker/WorkerDynamicPool.ts @@ -31,8 +31,8 @@ export class WorkerDynamicPool exten /** * Creates a new `WorkerDynamicPool`. - * @param workerScript - - * @param workerOptions - + * @param workerScript - Path to the worker script file + * @param workerOptions - Worker pool configuration options */ constructor (workerScript: string, workerOptions: WorkerOptions) { super(workerScript, workerOptions) diff --git a/src/worker/WorkerFixedPool.ts b/src/worker/WorkerFixedPool.ts index f5d9b01e..c05864d1 100644 --- a/src/worker/WorkerFixedPool.ts +++ b/src/worker/WorkerFixedPool.ts @@ -31,8 +31,8 @@ export class WorkerFixedPool extends /** * Creates a new `WorkerFixedPool`. - * @param workerScript - - * @param workerOptions - + * @param workerScript - Path to the worker script file + * @param workerOptions - Worker pool configuration options */ constructor (workerScript: string, workerOptions: WorkerOptions) { super(workerScript, workerOptions) diff --git a/src/worker/WorkerSet.ts b/src/worker/WorkerSet.ts index c5ae6ed2..78a47e72 100644 --- a/src/worker/WorkerSet.ts +++ b/src/worker/WorkerSet.ts @@ -59,8 +59,8 @@ export class WorkerSet extends Worke /** * Creates a new `WorkerSet`. - * @param workerScript - - * @param workerOptions - + * @param workerScript - Path to the worker script file + * @param workerOptions - Worker set configuration options */ constructor (workerScript: string, workerOptions: WorkerOptions) { super(workerScript, workerOptions) -- 2.43.0