From d37c79751f28ae11b4a4b1294afa69ff3c934685 Mon Sep 17 00:00:00 2001 From: ciatph Date: Fri, 13 Sep 2024 03:39:21 +0800 Subject: [PATCH] docs: use correct jsdoc type annotations --- .../classInitialization/checkClass.js | 2 +- .../createMunicipalityInstance.js | 4 +- app/src/classes/colorlog/index.js | 22 +++++----- app/src/classes/excel/index.js | 42 ++++++++++--------- app/src/classes/excelfactory/index.js | 4 +- app/src/classes/schema/index.js | 4 +- app/src/lib/utils.js | 8 ++-- 7 files changed, 44 insertions(+), 42 deletions(-) diff --git a/app/__tests__/classInitialization/checkClass.js b/app/__tests__/classInitialization/checkClass.js index d289501..efad34b 100644 --- a/app/__tests__/classInitialization/checkClass.js +++ b/app/__tests__/classInitialization/checkClass.js @@ -4,7 +4,7 @@ * Checks valid `ExcelFile` or `ExcelFactory` class instances. * @typedef {Object} params - Input parameters * @param {Function} excelInstance - `ExcelFile` or `ExcelFactory` class instance - * @param {Bool} isRemote - Flag if the Excel data source is from a remote download. Defaults to `false`. + * @param {boolean} isRemote - Flag if the Excel data source is from a remote download. Defaults to `false`. * @param {Function} classType - `ExcelFile` or `ExcelFactory` class */ const checkClass = ({ excelInstance, isRemote = false, classType = null }) => { diff --git a/app/__tests__/municipalities/createMunicipalityInstance.js b/app/__tests__/municipalities/createMunicipalityInstance.js index 6b79a32..ec11476 100644 --- a/app/__tests__/municipalities/createMunicipalityInstance.js +++ b/app/__tests__/municipalities/createMunicipalityInstance.js @@ -7,8 +7,8 @@ const logger = new ColorLog({ color: ColorLog.COLORS.TEXT.YELLOW, isBold: true } * Builds objects containing all provinces AND municipality names for the PAGASA seasonal config and 10-Day Excel file to use for comparison checks and logs viewing purposes only. * @param {Class} excelFile - `ExcelFile` or `ExcelFactory` instance * @returns {Object} Object containing Arrays and Sets of province and municipality names - * - `hasMissingInExcel` {Bool} - Flag if province(s) exist in the PAGASA seasonal config but not in the 10-day Excel - * - `hasMissingInConfig` {Bool} - Flag if municipalities exist in 10-day Excel but not in the municipalities list built from the PAGASA seasonal config + * - `hasMissingInExcel` {boolean} - Flag if province(s) exist in the PAGASA seasonal config but not in the 10-day Excel + * - `hasMissingInConfig` {boolean} - Flag if municipalities exist in 10-day Excel but not in the municipalities list built from the PAGASA seasonal config * - `excel` {Object} - Contains full province/municipality names and data from the 10-day Excel file * - `excel.provinces` {String[]} - all provinces from the 10-day Excel file * - `excel.municipalities` {Object} - Object with province names as keys and values are String[] array of municipalities under the province diff --git a/app/src/classes/colorlog/index.js b/app/src/classes/colorlog/index.js index 4c4bab7..7ab025a 100644 --- a/app/src/classes/colorlog/index.js +++ b/app/src/classes/colorlog/index.js @@ -33,9 +33,9 @@ class ColorLog { /** * Initializes a ColorLog class - * @typedef {Object} params - Input parameters - * @param {String} params.color - ANSI color defined in `ColorLog.COLORS` - * @param {Bool} params.isBold - Flag to render bold colored text + * @param {Object} params - Input parameters + * @param {string} params.color - ANSI color defined in `ColorLog.COLORS` + * @param {boolean} params.isBold - Flag to render bold colored text */ constructor ({ color, isBold = false } = {}) { this.setColor(color) @@ -44,11 +44,11 @@ class ColorLog { /** * Prints colored log message in console.log() - * @param {String} message - Log message text + * @param {string} message - Log message text * @param {Object} options - (Optional) - * @param {String} options.color - ANSI color defined in `ColorLog.COLORS` - * @param {Bool} options.isBold - Flag to render bold colored text - * @returns {Bool} + * @param {string} options.color - ANSI color defined in `ColorLog.COLORS` + * @param {boolean} options.isBold - Flag to render bold colored text + * @returns {boolean} */ log (message, options = {}) { if (!message || typeof message !== 'string') return @@ -63,8 +63,8 @@ class ColorLog { /** * Sets the text color in console.log() - * @param {String} color - ANSI color defined in `ColorLog.COLORS` - * @returns {Bool} + * @param {string} color - ANSI color defined in `ColorLog.COLORS` + * @returns {boolean} */ setColor (color) { if (!color) return @@ -78,8 +78,8 @@ class ColorLog { /** * Sets the text weight in console.log - * @param {Bool} isBold - Flag to render bold colored text - * @returns {Bool} + * @param {boolean} isBold - Flag to render bold colored text + * @returns {boolean} */ setText (isBold) { if (![true, false].includes(isBold)) return diff --git a/app/src/classes/excel/index.js b/app/src/classes/excel/index.js index 77d5afc..6c36240 100644 --- a/app/src/classes/excel/index.js +++ b/app/src/classes/excel/index.js @@ -37,12 +37,14 @@ class ExcelFile { /** * SheetJS array index number translated from the Excel headers row count * before elements containing "municipalityName (provinceName)" data + * @type {number} */ dataRowStart: 0, /** Internal excel file column name read by sheetjs. * This column contains strings following the pattern * "municipalityName (provinceName)" + * @type {string} */ SHEETJS_COL: process.env.SHEETJS_COLUMN || '__EMPTY' } @@ -73,14 +75,14 @@ class ExcelFile { /** * Initialize an ExcelFile object - * @typedef {Object} params - Constructor parameter Object - * @param {String} [params.url] - (Optional) Remote download URL of an excel file - * @param {String} params.pathToFile + * @param {Object} params - Constructor parameter Object + * @param {string} [params.url] - (Optional) Remote download URL of an excel file + * @param {string} params.pathToFile * - Full local file path of an existing Excel file, **required** if `params.url` is not provided * - Full local file path to an existing or non-existent Excel file on which to download/save the remote Excel file from `params.url`, * if the `params.url` parameter is provided * @param {Object} [params.settings] - (Optional) Region settings configuration object following the format of the `/app/config/regions.json` file. Defaults to the mentioned file if not provided. - * @param {Bool} [params.fastload] - (Optional) Start loading and parsing the local excel file on class initialization if the "url" param is not provided. + * @param {boolean} [params.fastload] - (Optional) Start loading and parsing the local excel file on class initialization if the "url" param is not provided. * - If `false` or not provided, call the `.init()` method later on a more convenient time. */ constructor ({ url, pathToFile, fastload = true, settings = null, options = null } = {}) { @@ -233,8 +235,8 @@ class ExcelFile { /** * Checks if a string follows the pattern: * "municipalityName (provinceName)" - * @param {String} str - String to check - * @returns {Bool} true | false + * @param {string} str - String to check + * @returns {boolean} true | false */ followsStringPattern (str) { return /[a-zA-Z,.] *\([^)]*\) *$/.test(str) @@ -243,7 +245,7 @@ class ExcelFile { /** * Sets the local this.#options settings * @param {Object} options - Miscellaneous app settings defined in this.#options - * @returns {Bool} + * @returns {boolean} */ setOptions (options) { if (!options) return false @@ -257,8 +259,8 @@ class ExcelFile { /** * Checks if a string contains special characters - * @param {String} str - String to check - * @returns {Bool} + * @param {string} str - String to check + * @returns {boolean} */ static hasSpecialChars (str) { /* eslint-disable no-control-regex */ @@ -268,8 +270,8 @@ class ExcelFile { /** * Cleans/removes default-known special characters and garbled text defined in config from string. - * @param {String} str - String to clean - * @returns {String} - Clean string + * @param {string} str - String to clean + * @returns {string} - Clean string */ static removeGarbledText (str) { // Known garbled special text @@ -304,8 +306,8 @@ class ExcelFile { /** * Extracts the municipality name from a string following the pattern: * "municipalityName (provinceName)" - * @param {String} str - * @returns {String} municipality name + * @param {string} str + * @returns {string} municipality name */ getMunicipalityName (str) { const municipalityName = str.replace(/ *\([^)]*\) */g, '') @@ -320,8 +322,8 @@ class ExcelFile { /** * Extracts the province name from a string following the pattern: * "municipalityName (provinceName)" - * @param {String} str - * @returns {String} province name + * @param {string} str + * @returns {string} province name * @returns {null} Returns null if "provinceName" is not found */ getProvinceName (str) { @@ -436,8 +438,8 @@ class ExcelFile { * Writes queried municipalities data to a JSON file. * Lists municipalities by by provinces. * @param {String[]} provinces - Array of case-sensitive province names. Starts with an upper case. - * @param {String} fielName - Full file path to a JSON file - * @param {Bool} prettify - Write the JSON content with proper spacings and newlines + * @param {string} fielName - Full file path to a JSON file + * @param {boolean} prettify - Write the JSON content with proper spacings and newlines * @returns {Object} Formatted raw data with misc. metadata */ writeMunicipalities ({ provinces, fileName, prettify = false }) { @@ -466,7 +468,7 @@ class ExcelFile { /** * Lists the province names of a region defined in the settings file - * @param {String} regionName - Region name that matches with the `/app/config/regions.json` file's `data[N].name` + * @param {string} regionName - Region name that matches with the `/app/config/regions.json` file's `data[N].name` * @returns {String[]} List provinces under the `regionName`. */ listProvinces (regionName) { @@ -476,8 +478,8 @@ class ExcelFile { /** * Lists the province names of a region defined in the settings (PAGASA seasonal config) file or from the parsed Excel file - * @param {String} region - Region name that matches with the `/app/config/regions.json` file's `data[N].name` - * @param {Bool} fromExcel - Flag to return the province names from the parsed 10-day Excel file. Defaults to `false`. + * @param {string} region - Region name that matches with the `/app/config/regions.json` file's `data[N].name` + * @param {boolean} fromExcel - Flag to return the province names from the parsed 10-day Excel file. Defaults to `false`. * - Note: Province names from a "remote" Excel file may change without notice. * - It may differ from the contents of the "default" settings (PAGASA seasonal config) file. * - If the province names from the "remote" Excel file and "default" settings (PAGASA seasonal config) file vary, diff --git a/app/src/classes/excelfactory/index.js b/app/src/classes/excelfactory/index.js index 749dae6..f4307fe 100644 --- a/app/src/classes/excelfactory/index.js +++ b/app/src/classes/excelfactory/index.js @@ -16,8 +16,8 @@ const ExcelFile = require('../excel') class ExcelFactory extends ExcelFile { /** * Initializes an `ExcelFactory` class. - * @typedef {Object} params - Constructor parameter Object - * @param {String} [params.url] - (Optional) Remote download URL of an excel file + * @param {Object} params - Constructor parameter Object + * @param {string} [params.url] - (Optional) Remote download URL of an excel file * @param {Object} [params.settings] - (Optional) Region settings configuration object following the format of the `/app/config/regions.json` file. Defaults to the mentioned file if not provided. */ constructor ({ url, settings } = {}) { diff --git a/app/src/classes/schema/index.js b/app/src/classes/schema/index.js index 75bb785..6e4c960 100644 --- a/app/src/classes/schema/index.js +++ b/app/src/classes/schema/index.js @@ -1,5 +1,5 @@ /** - * Validates Objects with zod schemas and formats validation error(s) for log output. + * Validates Objects with [zod](https://github.com/colinhacks/zod) schemas and formats validation error(s) for log output. */ class Schema { /** Settings object */ @@ -44,7 +44,7 @@ class Schema { /** * Formats error messages into a single string * @param {Object[]} errors - List of zod error messages - * @returns {Bool} + * @returns {boolean} */ formatErrorLog (errors = []) { if (!Array.isArray(errors)) { diff --git a/app/src/lib/utils.js b/app/src/lib/utils.js index cf2a6bb..12ce251 100644 --- a/app/src/lib/utils.js +++ b/app/src/lib/utils.js @@ -1,7 +1,7 @@ /** * Checks if a variable is a true JavaScript Object * @param {Object} item - JavaScript Object - * @returns {Bool} true|false + * @returns {boolean} true|false */ const isObject = (item) => { return item && @@ -12,14 +12,14 @@ const isObject = (item) => { /** * Converts an Array of strings (text) into a single comma-separated string * @param {String[]} arrayOfText - Array containing String items - * @returns {String} Comma-separated text + * @returns {string} Comma-separated text */ const arrayToString = (arrayOfText) => arrayOfText.toString().split(',').join(', ') /** * Capitalizes the first letter of words in a text - * @param {String} text - String text - * @returns {String} Capitalized text + * @param {string} text - String text + * @returns {string} Capitalized text */ const capitalizeText = (text) => { if (typeof text !== 'string') return null