From 9a20aa900366297d7e3535343bf0ef96629269f8 Mon Sep 17 00:00:00 2001 From: Okinea Dev <81070564+okineadev@users.noreply.github.com> Date: Wed, 6 Nov 2024 12:52:30 +0200 Subject: [PATCH] docs: improve TSDoc comments throughout the project (#2671) --- src/core/generator/applyConfigToIcons.ts | 4 +- src/core/generator/clones/clonesGenerator.ts | 22 +++-- src/core/generator/clones/utils/cloneData.ts | 47 ++++++++-- src/core/generator/clones/utils/cloning.ts | 57 ++++++++++-- src/core/generator/fileGenerator.ts | 42 ++++++++- src/core/generator/folderGenerator.ts | 93 +++++++++++++++++++- src/core/generator/iconOpacity.ts | 47 +++++++--- src/core/generator/iconSaturation.ts | 61 +++++++++---- src/core/generator/languageGenerator.ts | 54 ++++++++++-- src/core/generator/renameIconFiles.ts | 2 +- 10 files changed, 365 insertions(+), 64 deletions(-) diff --git a/src/core/generator/applyConfigToIcons.ts b/src/core/generator/applyConfigToIcons.ts index ca0f7b3f1d..cc3e588b92 100644 --- a/src/core/generator/applyConfigToIcons.ts +++ b/src/core/generator/applyConfigToIcons.ts @@ -8,8 +8,8 @@ import { setIconSaturation } from './iconSaturation'; * Apply the configuration to the icons. But only if the configuration has changed. * If the affectedConfig is not set then all icons will be updated. * - * @param config Configuration that customizes the icons and the manifest. - * @param affectedConfig Set of configuration keys that have changed so that not all functions need to be executed. + * @param config - The new configuration that customizes the icons and the manifest. + * @param oldConfig - The previous configuration to compare changes. */ export const applyConfigToIcons = async (config: Config, oldConfig: Config) => { if (config.files.color !== oldConfig.files.color) { diff --git a/src/core/generator/clones/clonesGenerator.ts b/src/core/generator/clones/clonesGenerator.ts index c9b99b8ff1..5065780ca3 100644 --- a/src/core/generator/clones/clonesGenerator.ts +++ b/src/core/generator/clones/clonesGenerator.ts @@ -18,6 +18,10 @@ import { cloneIcon, createCloneConfig } from './utils/cloning'; /** * Creates custom icons by cloning already existing icons and changing * their colors, based on the user's provided configurations. + * + * @param manifest - The current configuration of the extension. + * @param config - The new configuration that customizes the icons and the manifest. + * @returns A promise that resolves to the updated manifest with custom clones. */ export const customClonesIcons = async ( manifest: Manifest, @@ -55,6 +59,9 @@ export const customClonesIcons = async ( * Creates custom icons by cloning already existing icons and changing * their colors, based on the configurations provided by the extension. * (this is meant to be called at build time) + * + * @param iconsList - The list of icons to be cloned. + * @param manifest - The current configuration of the extension. */ export const generateConfiguredClones = async ( iconsList: FolderTheme[] | FileIcons, @@ -107,7 +114,12 @@ export const generateConfiguredClones = async ( } }; -/** Checks if there are any custom clones to be created */ +/** + * Checks if there are any custom clones to be created. + * + * @param config - The new configuration that customizes the icons and the manifest. + * @returns True if there are custom clones to be created, false otherwise. + */ export const hasCustomClones = (config: Config): boolean => { return ( (config.folders?.customClones?.length ?? 0) > 0 || @@ -117,10 +129,10 @@ export const hasCustomClones = (config: Config): boolean => { /** * Generates a clone of an icon. - * @param cloneOpts options and configurations on how to clone the icon - * @param manifest global icon configuration (used to get the base icon) - * @param hash current hash being applied to the icons - * @returns a partial icon configuration for the new icon + * @param cloneOpts - Options and configurations on how to clone the icon. + * @param manifest - Global icon configuration (used to get the base icon). + * @param hash - Current hash being applied to the icons. + * @returns A promise that resolves to a partial icon configuration for the new icon. */ const createIconClone = async ( cloneOpts: FolderIconClone | FileIconClone, diff --git a/src/core/generator/clones/utils/cloneData.ts b/src/core/generator/clones/utils/cloneData.ts index 0a3eeb9961..320f4d7502 100644 --- a/src/core/generator/clones/utils/cloneData.ts +++ b/src/core/generator/clones/utils/cloneData.ts @@ -50,9 +50,11 @@ const isDark = (daa: IconData) => /** * get cloning information from configuration - * @param cloneOpts the clone configuration - * @param manifest the current configuration of the extension - * @param hash the current hash being applied to the icons + * @param cloneOpts - The clone configuration. + * @param manifest - The current configuration of the extension. + * @param subFolder - The subfolder where the cloned icons will be stored. + * @param hash - The current hash being applied to the icons. + * @param ext - The file extension for the cloned icons */ export const getCloneData = ( cloneOpts: CustomClone, @@ -75,7 +77,7 @@ export const getCloneData = ( name: getIconName(cloneOpts.name, base), color: isDark(base) ? cloneOpts.color - : cloneOpts.lightColor ?? cloneOpts.color, + : (cloneOpts.lightColor ?? cloneOpts.color), inConfigPath: `${iconFolderPath}${subFolder}${basename( cloneIcon.path )}`, @@ -86,7 +88,11 @@ export const getCloneData = ( } }; -/** returns path, type and variant for the base file icons to be cloned */ +/** + * returns path, type and variant for the base file icons to be cloned + * @param cloneOpts - The clone configuration. + * @param manifest - The current configuration of the extension. + */ const getFileIconBaseData = ( cloneOpts: FileIconClone, manifest: Manifest @@ -118,7 +124,15 @@ const getFileIconBaseData = ( } }; -/** creates and returns the path of the cloned file icon */ +/** + * Creates and returns the path of the cloned file icon + * + * @param base - The base icon data. + * @param cloneOpts - The clone configuration. + * @param hash - The current hash being applied to the icons. + * @param subFolder - The subfolder where the cloned icons will be stored. + * @param ext - The file extension for the cloned icons. + */ const getFileIconCloneData = ( base: IconData, cloneOpts: FileIconClone, @@ -136,7 +150,12 @@ const getFileIconCloneData = ( }; }; -/** returns path, type and variant for the base folder icons to be cloned */ +/** + * returns path, type and variant for the base folder icons to be cloned + * + * @param clone - The folder clone configuration. + * @param manifest - The current configuration of the extension. + */ const getFolderIconBaseData = ( clone: FolderIconClone, manifest: Manifest @@ -199,7 +218,15 @@ const getFolderIconBaseData = ( } }; -/** creates and returns the path of the cloned folder icon */ +/** + * Creates and returns the path of the cloned folder icon + * + * @param base - The base icon data. + * @param cloneOpts - The clone configuration. + * @param hash - The current hash being applied to the icons. + * @param subFolder - The subfolder where the cloned icons will be stored. + * @param ext - The file extension for the cloned icons. + */ const getFolderIconCloneData = ( base: IconData, cloneOpts: FolderIconClone, @@ -213,8 +240,10 @@ const getFolderIconCloneData = ( }; /** - * removes the clones folder if it exists + * Removes the clones folder if it exists * and creates a new one if `keep` is true + * + * @param keep whether to keep the folder after clearing it. */ export const clearCloneFolder = async (keep = true): Promise => { const clonesFolderPath = resolvePath('./../icons/clones'); diff --git a/src/core/generator/clones/utils/cloning.ts b/src/core/generator/clones/utils/cloning.ts index 367c7d0535..4723e3f93b 100644 --- a/src/core/generator/clones/utils/cloning.ts +++ b/src/core/generator/clones/utils/cloning.ts @@ -6,11 +6,15 @@ import { getColorList, replacementMap } from './color/colors'; /** * Recursively walks through an SVG node tree and its children, * calling a callback on each node. + * + * @param node - The SVG node to traverse. + * @param callback - The callback function to call on each node. + * @param filter - Whether to filter nodes with 'data-mit-no-recolor' attribute. */ export const traverse = ( node: INode, callback: (node: INode) => void, - filter = true + filter: boolean = true ) => { if (node.attributes['data-mit-no-recolor'] !== 'true' || !filter) { callback(node); @@ -21,7 +25,13 @@ export const traverse = ( } }; -/** Reads an icon from the file system and returns its content. */ +/** + * Reads an icon from the file system and returns its content. + * + * @param path - The path to the icon file. + * @param hash - The hash to be replaced in the path if the file is not found. + * @returns A promise that resolves to the content of the icon file. + */ export const readIcon = async (path: string, hash: string): Promise => { try { return await readFile(path, 'utf8'); @@ -31,7 +41,14 @@ export const readIcon = async (path: string, hash: string): Promise => { } }; -/** Clones an icon and changes its colors according to the clone options. */ +/** + * Clones an icon and changes its colors according to the clone options. + * + * @param path - The path to the icon file. + * @param color - The color to replace in the icon. + * @param hash - The hash to be replaced in the path if the file is not found. + * @returns A promise that resolves to the content of the cloned icon. + */ export const cloneIcon = async ( path: string, color: string, @@ -44,7 +61,12 @@ export const cloneIcon = async ( return stringify(svg); }; -/** Gets the style attribute of an SVG node if it exists. */ +/** + * Gets the style attribute of an SVG node if it exists. + * + * @param node - The SVG node to get the style attribute from. + * @returns The style attribute as an object. + */ export const getStyle = (node: INode) => { if (node && node.attributes && node.attributes.style) { return parseStyle(node.attributes.style); @@ -52,7 +74,12 @@ export const getStyle = (node: INode) => { return {}; }; -/** Parses the style attribute of an SVG node. */ +/** + * Parses the style attribute of an SVG node. + * + * @param css - The style attribute as a string. + * @returns The style attribute as an object. + */ const parseStyle = (css: string) => { const rules = css.split(';'); const result: Record = {}; @@ -63,14 +90,24 @@ const parseStyle = (css: string) => { return result; }; -/** Converts object to css style string. */ +/** + * Converts object to css style string. + * + * @param css - The style attribute as an object. + * @returns The style attribute as a string. + */ export const stringifyStyle = (css: Record) => { return Object.entries(css) .map(([key, value]) => `${key}:${value}`) .join(';'); }; -/** Replaces colors in an SVG node using a replacement map. */ +/** + * Replaces colors in an SVG node using a replacement map. + * + * @param node - The SVG node to replace colors in. + * @param replacements - The map of colors to replace. + */ export const replaceColors = ( node: INode, replacements: Map @@ -112,7 +149,11 @@ export const replaceColors = ( }); }; -/** Creates a clone configuration with empty light object. */ +/** + * Creates a clone configuration with empty light object. + * + * @returns A manifest object with empty light object. + */ export const createCloneConfig = () => { const manifest = createEmptyManifest(); manifest.light = { diff --git a/src/core/generator/fileGenerator.ts b/src/core/generator/fileGenerator.ts index afb51f5698..f27ec465ab 100644 --- a/src/core/generator/fileGenerator.ts +++ b/src/core/generator/fileGenerator.ts @@ -17,6 +17,11 @@ import { validateHEXColorCode } from './shared/validation'; /** * Get all file icons that can be used in this theme. + * + * @param fileIcons - The file icons to be used in the theme. + * @param config - The configuration object for the icons. + * @param manifest - The manifest object to be updated with the file icons. + * @returns The updated manifest object with the file icons. */ export const loadFileIconDefinitions = ( fileIcons: FileIcons, @@ -109,13 +114,19 @@ export const loadFileIconDefinitions = ( /** * Map the file extensions and the filenames to the related icons. + * + * @param icon - The file icon to be mapped. + * @param mappingType - The type of mapping (file extensions or file names). + * @param manifest - The manifest object to be updated with the mappings. + * @param customFileAssociation - Custom file associations to be considered. + * @returns The updated manifest object with the mappings. */ const mapSpecificFileIcons = ( icon: FileIcon, mappingType: FileMappingType, manifest: Manifest, customFileAssociation: IconAssociations = {} -) => { +): Manifest => { const iconMappingType = icon[mappingType as keyof FileIcon] as string[]; if (iconMappingType === undefined) { return manifest; @@ -161,6 +172,10 @@ const mapSpecificFileIcons = ( /** * Disable all file icons that are in a pack which is disabled. + * + * @param fileIcons - The file icons to be filtered. + * @param activeIconPack - The active icon pack to be considered. + * @returns The filtered file icons that are enabled for the active icon pack. */ const disableIconsByPack = ( fileIcons: FileIcons, @@ -173,13 +188,23 @@ const disableIconsByPack = ( }); }; +/** + * Set the icon definition in the manifest. + * + * @param manifest - The manifest object to be updated. + * @param config - The configuration object for the icons. + * @param iconName - The name of the icon. + * @param isClone - Whether the icon is a clone. + * @param appendix - The appendix to be added to the icon name. + * @returns The updated manifest object with the icon definition. + */ const setIconDefinition = ( manifest: Manifest, config: Config, iconName: string, isClone: boolean, appendix: string = '' -) => { +): Manifest => { const ext = isClone ? cloneIconExtension : '.svg'; const key = `${iconName}${appendix}`; manifest.iconDefinitions ??= {}; @@ -192,6 +217,13 @@ const setIconDefinition = ( return manifest; }; +/** + * Generate the file icons with the specified color, opacity, and saturation. + * + * @param color - The color of the file icons. + * @param opacity - The opacity of the file icons. + * @param saturation - The saturation of the file icons. + */ export const generateFileIcons = async ( color: string, opacity: number, @@ -212,6 +244,12 @@ export const generateFileIcons = async ( ); }; +/** + * Get the custom icons based on the file associations. + * + * @param fileAssociations - The file associations to be considered. + * @returns The custom icons based on the file associations. + */ const getCustomIcons = (fileAssociations: IconAssociations | undefined) => { if (!fileAssociations) return []; diff --git a/src/core/generator/folderGenerator.ts b/src/core/generator/folderGenerator.ts index ba15c9b7e1..cc8c5ae00a 100644 --- a/src/core/generator/folderGenerator.ts +++ b/src/core/generator/folderGenerator.ts @@ -19,6 +19,11 @@ import { validateHEXColorCode } from './shared/validation'; /** * Get the folder icon definitions as object. + * + * @param folderIcons - The folder icons to be used in the theme. + * @param config - The configuration object for the icons. + * @param manifest - The manifest object to be updated with the folder icons. + * @returns The updated manifest object with the folder icons. */ export const loadFolderIconDefinitions = ( folderIcons: FolderTheme[], @@ -63,6 +68,11 @@ export const loadFolderIconDefinitions = ( /** * Set the default folder icons for the theme. + * + * @param theme - The folder theme to be used. + * @param manifest - The manifest object to be updated with the default folder icons. + * @param config - The configuration object for the icons. + * @returns The updated manifest object with the default folder icons. */ const setDefaultFolderIcons = ( theme: FolderTheme, @@ -132,6 +142,10 @@ const setDefaultFolderIcons = ( /** * Get the object of the current enabled theme. + * + * @param themes - The list of available folder themes. + * @param enabledTheme - The name of the enabled theme. + * @returns The enabled folder theme, or undefined if not found. */ const getEnabledFolderTheme = ( themes: FolderTheme[], @@ -142,6 +156,10 @@ const getEnabledFolderTheme = ( /** * Disable all file icons that are in a pack which is disabled. + * + * @param folderIcons - The folder icons to be filtered. + * @param activatedIconPack - The active icon pack to be considered. + * @returns The filtered folder icons that are enabled for the active icon pack. */ const disableIconsByPack = ( folderIcons: FolderTheme | undefined, @@ -157,6 +175,15 @@ const disableIconsByPack = ( }); }; +/** + * Set the icon definitions in the manifest. + * + * @param manifest - The manifest object to be updated. + * @param config - The configuration object for the icons. + * @param icon - The icon to be set in the manifest. + * @param appendix - The appendix to be added to the icon name. + * @returns The updated manifest object with the icon definitions. + */ const setIconDefinitions = ( manifest: Manifest, config: Config, @@ -164,7 +191,14 @@ const setIconDefinitions = ( ) => { const isClone = (icon as FolderIcon).clone !== undefined; - manifest = createIconDefinitions(manifest, config, icon.name, '', isClone); + manifest = createIconDefinitions( + manifest, + config, + icon.name, + '', + isClone + ); + if (icon.light) { manifest = merge( manifest, @@ -192,13 +226,23 @@ const setIconDefinitions = ( return manifest; }; +/** + * Create the icon definitions in the manifest. + * + * @param manifest - The manifest object to be updated. + * @param config - The configuration object for the icons. + * @param iconName - The name of the icon. + * @param appendix - The appendix to be added to the icon name. + * @param isClone - Whether the icon is a clone. + * @returns The updated manifest object with the icon definitions. + */ const createIconDefinitions = ( manifest: Manifest, config: Config, iconName: string, appendix: string = '', isClone = false -) => { +): Manifest => { const fileConfigHash = getFileConfigHash(config); const configIconDefinitions = manifest.iconDefinitions; const ext = isClone ? cloneIconExtension : '.svg'; @@ -221,6 +265,12 @@ const createIconDefinitions = ( return manifest; }; +/** + * Extend the folder names with additional styles. + * + * @param folderNames - The folder names to be extended. + * @returns The extended folder names. + */ const extendFolderNames = (folderNames: string[]) => { const names: string[] = []; const styles: [string, string][] = [ @@ -237,11 +287,19 @@ const extendFolderNames = (folderNames: string[]) => { return names; }; +/** + * Set the folder names in the manifest. + * + * @param iconName - The name of the icon. + * @param folderNames - The folder names to be set in the manifest. + * @param appendix - The appendix to be added to the icon name. + * @returns The partial manifest object with the folder names. + */ const setFolderNames = ( iconName: string, folderNames: string[], appendix: string = '' -) => { +): Partial => { const obj: Partial = { folderNames: {}, folderNamesExpanded: {}, @@ -258,6 +316,14 @@ const setFolderNames = ( return obj; }; +/** + * Create the default icon configuration object. + * + * @param hasFolderIcons - Whether the theme has folder icons. + * @param theme - The folder theme to be used. + * @param appendix - The appendix to be added to the icon name. + * @returns The default icon configuration object. + */ const createDefaultIconConfigObject = ( hasFolderIcons: boolean, theme: FolderTheme, @@ -274,6 +340,14 @@ const createDefaultIconConfigObject = ( return obj; }; +/** + * Create the root icon configuration object. + * + * @param hasFolderIcons - Whether the theme has folder icons. + * @param theme - The folder theme to be used. + * @param appendix - The appendix to be added to the icon name. + * @returns The root icon configuration object. + */ const createRootIconConfigObject = ( hasFolderIcons: boolean, theme: FolderTheme, @@ -296,6 +370,12 @@ const createRootIconConfigObject = ( return obj; }; +/** + * Get the custom icons based on the folder associations. + * + * @param folderAssociations - The folder associations to be considered. + * @returns The custom icons based on the folder associations. + */ const getCustomIcons = (folderAssociations: IconAssociations | undefined) => { if (!folderAssociations) return []; @@ -311,6 +391,13 @@ const getCustomIcons = (folderAssociations: IconAssociations | undefined) => { return icons; }; +/** + * Generate the folder icons with the specified color, opacity, and saturation. + * + * @param color - The color of the folder icons. + * @param opacity - The opacity of the folder icons. + * @param saturation - The saturation of the folder icons. + */ export const generateFolderIcons = async ( color: string, opacity: number, diff --git a/src/core/generator/iconOpacity.ts b/src/core/generator/iconOpacity.ts index 0e41a20373..817e6aa6cc 100644 --- a/src/core/generator/iconOpacity.ts +++ b/src/core/generator/iconOpacity.ts @@ -8,7 +8,9 @@ import { iconFolderPath } from './constants'; /** * Changes the opacity of all icons in the set. - * @param config Icon JSON options which include the opacity value. + * + * @param opacity - The opacity value to be applied to the icons. + * @param filesAssociations - The file associations to be considered. */ export const setIconOpacity = async ( opacity: number, @@ -45,27 +47,33 @@ export const setIconOpacity = async ( /** * Validate the opacity value. - * @param opacity Opacity value + * + * @param opacity - The opacity value to be validated. + * @returns True if the opacity value is valid, false otherwise. */ -export const validateOpacityValue = (opacity: number | undefined) => { +export const validateOpacityValue = (opacity: number | undefined): boolean => { return opacity !== undefined && opacity <= 1 && opacity >= 0; }; /** * Get the SVG root element. - * @param svg SVG file as string. + * + * @param svg - The SVG file as a string. + * @returns The root element of the SVG. */ -const getSVGRootElement = (svg: string) => { +const getSVGRootElement = (svg: string): string | undefined => { const result = new RegExp(/]*>/).exec(svg); return result?.[0]; }; /** * Add an opacity attribute to the SVG icon to control the opacity of the icon. - * @param svgRoot Root element of the SVG icon. - * @param opacity Opacity value. + * + * @param svgRoot - The root element of the SVG icon. + * @param opacity - The opacity value to be added. + * @returns The updated SVG root element with the opacity attribute. */ -const addOpacityAttribute = (svgRoot: string, opacity: number) => { +const addOpacityAttribute = (svgRoot: string, opacity: number): string => { const pattern = new RegExp(/\sopacity="[\d.]+"/); // if the opacity attribute already exists if (pattern.test(svgRoot)) { @@ -77,14 +85,22 @@ const addOpacityAttribute = (svgRoot: string, opacity: number) => { /** * Remove the opacity attribute of the SVG icon. - * @param svgRoot Root element of the SVG icon. + * + * @param svgRoot - The root element of the SVG icon. + * @returns The updated SVG root element without the opacity attribute. */ -const removeOpacityAttribute = (svgRoot: string) => { +const removeOpacityAttribute = (svgRoot: string): string => { const pattern = new RegExp(/\sopacity="[\d.]+"/); return svgRoot.replace(pattern, ''); }; -/** Function to add or remove opacity from a given SVG string */ +/** + * Add or remove opacity from a given SVG string. + * + * @param svg - The SVG file as a string. + * @param opacity - The opacity value to be applied. + * @returns The updated SVG file with the applied opacity. + */ export const updateSVGOpacity = (svg: string, opacity: number): string => { const svgRootElement = getSVGRootElement(svg); if (!svgRootElement) return svg; @@ -98,7 +114,14 @@ export const updateSVGOpacity = (svg: string, opacity: number): string => { return svg.replace(/]*>/, updatedRootElement); }; -/** Function to read an SVG file, update its opacity, and write it back */ +/** + * Read an SVG file, update its opacity, and write it back. + * + * @param iconPath - The path to the icon file. + * @param iconFileName - The name of the icon file. + * @param opacity - The opacity value to be applied. + * @returns A promise that resolves when the file has been processed. + */ const processSVGFile = async ( iconPath: string, iconFileName: string, diff --git a/src/core/generator/iconSaturation.ts b/src/core/generator/iconSaturation.ts index 15899c1e28..5ae36e93be 100644 --- a/src/core/generator/iconSaturation.ts +++ b/src/core/generator/iconSaturation.ts @@ -8,8 +8,9 @@ import { iconFolderPath } from './constants'; /** * Changes saturation of all icons in the set. - * @param config Icon JSON options which include the saturation value. - * @param fileNames Only change the saturation of certain file names. + * + * @param saturation - The saturation value to be applied to the icons. + * @param filesAssociations - The file associations to be considered. */ export const setIconSaturation = async ( saturation: number, @@ -46,18 +47,22 @@ export const setIconSaturation = async ( /** * Get the SVG root element. - * @param svg SVG file as string. + * + * @param svg - The SVG file as a string. + * @returns The root element of the SVG. */ -const getSVGRootElement = (svg: string) => { +const getSVGRootElement = (svg: string): string | undefined => { const result = new RegExp(/]*>/).exec(svg); return result?.[0]; }; /** * Add an filter attribute to the SVG icon. - * @param svgRoot Root element of the SVG icon. + * + * @param svgRoot - The root element of the SVG icon. + * @returns The updated SVG root element with the filter attribute. */ -const addFilterAttribute = (svgRoot: string) => { +const addFilterAttribute = (svgRoot: string): string => { const pattern = new RegExp(/\sfilter="[^"]+?"/); // if the filter attribute already exists if (pattern.test(svgRoot)) { @@ -69,18 +74,23 @@ const addFilterAttribute = (svgRoot: string) => { /** * Remove the filter attribute of the SVG icon. - * @param svgRoot Root element of the SVG icon. + * + * @param svgRoot - The root element of the SVG icon. + * @returns The updated SVG root element without the filter attribute. */ -const removeFilterAttribute = (svgRoot: string) => { +const removeFilterAttribute = (svgRoot: string): string => { const pattern = new RegExp(/\sfilter="[^"]+?"/); return svgRoot.replace(pattern, ''); }; /** * Add filter element to the SVG icon. - * @param svg SVG file as string. + * + * @param svg - The SVG file as a string. + * @param saturation - The saturation value to be applied. + * @returns The updated SVG file with the filter element. */ -const addFilterElement = (svg: string, saturation: number) => { +const addFilterElement = (svg: string, saturation: number): string => { const pattern = new RegExp(/(.*<\/svg>)/); const filterElement = ``; if (pattern.test(svg)) { @@ -92,22 +102,34 @@ const addFilterElement = (svg: string, saturation: number) => { /** * Remove filter element from the SVG icon. - * @param svg SVG file as string. + * + * @param svg - The SVG file as a string. + * @returns The updated SVG file without the filter element. */ -const removeFilterElement = (svg: string) => { +const removeFilterElement = (svg: string): string => { const pattern = new RegExp(/(.*<\/svg>)/); return svg.replace(pattern, '$1'); }; /** * Validate the saturation value. - * @param saturation Saturation value + * + * @param saturation - The saturation value to be validated. + * @returns True if the saturation value is valid, false otherwise. */ -export const validateSaturationValue = (saturation: number | undefined) => { +export const validateSaturationValue = ( + saturation: number | undefined +): boolean => { return saturation !== undefined && saturation <= 1 && saturation >= 0; }; -/** Function to adjust the saturation of a given SVG string */ +/** + * Adjust the saturation of a given SVG string. + * + * @param svg - The SVG file as a string. + * @param saturation - The saturation value to be applied. + * @returns The updated SVG file with the applied saturation. + */ export const adjustSVGSaturation = ( svg: string, saturation: number @@ -135,7 +157,14 @@ export const adjustSVGSaturation = ( return updatedSVG; }; -/** Function to read an SVG file, adjust its saturation, and write it back */ +/** + * Read an SVG file, adjust its saturation, and write it back. + * + * @param iconPath - The path to the icon file. + * @param iconFileName - The name of the icon file. + * @param saturation - The saturation value to be applied. + * @returns A promise that resolves when the file has been processed. + */ const processSVGFileForSaturation = async ( iconPath: string, iconFileName: string, diff --git a/src/core/generator/languageGenerator.ts b/src/core/generator/languageGenerator.ts index 42b83e103f..10f7c6761e 100644 --- a/src/core/generator/languageGenerator.ts +++ b/src/core/generator/languageGenerator.ts @@ -12,7 +12,12 @@ import { } from './constants'; /** - * Get all file icons that can be used in this theme. + * Get all language icons that can be used in this theme. + * + * @param languageIcons - The language icons to be used in the theme. + * @param config - The configuration object for the icons. + * @param manifest - The manifest object to be updated with the language icons. + * @returns The updated manifest object with the language icons. */ export const loadLanguageIconDefinitions = ( languageIcons: LanguageIcon[], @@ -56,11 +61,19 @@ export const loadLanguageIconDefinitions = ( return manifest; }; +/** + * Set the icon definitions in the manifest. + * + * @param manifest - The manifest object to be updated. + * @param config - The configuration object for the icons. + * @param icon - The icon to be set in the manifest. + * @returns The updated manifest object with the icon definitions. + */ const setIconDefinitions = ( manifest: Manifest, config: Config, icon: DefaultIcon -) => { +): Manifest => { createIconDefinitions(manifest, config, icon.name); if (icon.light) { @@ -77,6 +90,13 @@ const setIconDefinitions = ( return manifest; }; +/** + * Create the icon definitions in the manifest. + * + * @param manifest - The manifest object to be updated. + * @param config - The configuration object for the icons. + * @param iconName - The name of the icon. + */ const createIconDefinitions = ( manifest: Manifest, config: Config, @@ -90,7 +110,17 @@ const createIconDefinitions = ( } }; -const setLanguageIdentifiers = (iconName: string, languageIds: string[]) => { +/** + * Set the language identifiers in the manifest. + * + * @param iconName - The name of the icon. + * @param languageIds - The language identifiers to be set in the manifest. + * @returns The partial manifest object with the language identifiers. + */ +const setLanguageIdentifiers = ( + iconName: string, + languageIds: string[] +): Partial => { const obj: Partial = { languageIds: {} }; languageIds.forEach((id) => { obj.languageIds![id as keyof Manifest] = iconName; @@ -98,7 +128,15 @@ const setLanguageIdentifiers = (iconName: string, languageIds: string[]) => { return obj; }; -const getCustomIcons = (languageAssociations: IconAssociations | undefined) => { +/** + * Get the custom icons based on the language associations. + * + * @param languageAssociations - The language associations to be considered. + * @returns The custom icons based on the language associations. + */ +const getCustomIcons = ( + languageAssociations: IconAssociations | undefined +): LanguageIcon[] => { if (!languageAssociations) return []; const icons: LanguageIcon[] = Object.keys(languageAssociations).map((fa) => ({ @@ -110,12 +148,16 @@ const getCustomIcons = (languageAssociations: IconAssociations | undefined) => { }; /** - * Disable all file icons that are in a pack which is disabled. + * Disable all language icons that are in a pack which is disabled. + * + * @param languageIcons - The language icons to be filtered. + * @param activatedIconPack - The active icon pack to be considered. + * @returns The filtered language icons that are enabled for the active icon pack. */ const disableLanguagesByPack = ( languageIcons: LanguageIcon[], activatedIconPack: IconPackValue | undefined -) => { +): LanguageIcon[] => { return languageIcons.filter((language) => { return !language.enabledFor ? true diff --git a/src/core/generator/renameIconFiles.ts b/src/core/generator/renameIconFiles.ts index 6fd01f5a77..87c9eff64c 100644 --- a/src/core/generator/renameIconFiles.ts +++ b/src/core/generator/renameIconFiles.ts @@ -11,7 +11,7 @@ import { iconFolderPath } from './constants'; * Rename all icon files according their respective config. * * The rename triggers a change event in VS Code, which will update the icons in the UI. - * @param config Icon Json Options + * @param config - The new configuration that customizes the icons and the manifest. */ export const renameIconFiles = (config: Config) => { const defaultIconPath = resolvePath(iconFolderPath);