docs: improve TSDoc comments throughout the project (#2671)

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) {

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,

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<void> => {
   const clonesFolderPath = resolvePath('./../icons/clones');

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<string> => {
   try {
     return await readFile(path, 'utf8');
@@ -31,7 +41,14 @@ export const readIcon = async (path: string, hash: string): Promise<string> => {
   }
 };
 
-/** 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,15 +61,25 @@ 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);
   }
   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<string, string> = {};
@@ -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<string, string>) => {
   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<string, string>
@@ -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 = {

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 [];