docs(ui): update JSDoc comments to resolve lint warnings

webapp/src/components/App/Singlestudy/explore/Debug/utils.ts

@@ -22,9 +22,7 @@ export type TreeData = Record<string, any> | string;
 // Utils
 ////////////////////////////////////////////////////////////////
 
-/**
- * Maps file types and folder to their corresponding icon components.
- */
+//Maps file types and folder to their corresponding icon components.
 const iconByFileType: Record<FileType | "folder", SvgIconComponent> = {
   matrix: DatasetIcon,
   json: DataObjectIcon,
@@ -34,17 +32,19 @@ const iconByFileType: Record<FileType | "folder", SvgIconComponent> = {
 
 /**
  * Gets the icon component for a given file type or folder.
- * @param {FileType | "folder"} type - The type of the file or "folder".
- * @returns {SvgIconComponent} The corresponding icon component.
+ *
+ * @param type - The type of the file or "folder".
+ * @returns The corresponding icon component.
  */
 export const getFileIcon = (type: FileType | "folder"): SvgIconComponent => {
   return iconByFileType[type] || TextSnippetIcon;
 };
 
 /**
  * Determines the file type based on the tree data.
- * @param {TreeData} treeData - The data of the tree item.
- * @returns {FileType | "folder"} The determined file type or "folder".
+ *
+ * @param treeData - The data of the tree item.
+ * @returns The determined file type or "folder".
  */
 export const determineFileType = (treeData: TreeData): FileType | "folder" => {
   if (typeof treeData === "string") {
@@ -63,8 +63,9 @@ export const determineFileType = (treeData: TreeData): FileType | "folder" => {
 
 /**
  * Filters out specific keys from the tree data.
- * @param {TreeData} data - The original tree data.
- * @returns {TreeData} The filtered tree data.
+ *
+ * @param data - The original tree data.
+ * @returns The filtered tree data.
  */
 export const filterTreeData = (data: TreeData): TreeData => {
   const excludedKeys = new Set(["Desktop", "study", "logs"]);

webapp/src/components/App/Singlestudy/explore/Modelization/Areas/Hydro/utils.ts

@@ -210,6 +210,7 @@ export const MATRICES: Matrices = {
 
 /**
  * Generates an array of column names from 0 to 100, optionally with a suffix.
+ *
  * @param columnSuffix The suffix to append to the column names.
  * @returns An array of strings representing column names from 0 to 100.
  */

webapp/src/components/App/Singlestudy/explore/Modelization/Areas/common/utils.ts

@@ -20,17 +20,21 @@ export const saveField = R.curry(
 
 /**
  * Custom aggregation function summing the values of each row,
- * to display enabled and installed capacity in the same cell.
- * @param colHeader - the column header
- * @param rows - the column rows to aggregate
- * @returns a string with the sum of enabled and installed capacity.
- * @example "100/200"
- * @see https://www.material-react-table.com/docs/guides/aggregation-and-grouping#custom-aggregation-functions
+ * to display enabled and installed capacity in the same cell. This function is
+ * designed for use with Material React Table's custom aggregation feature, allowing
+ * the combination of enabled and installed capacities into a single cell.
+ *
+ * @returns A string representing the sum of enabled and installed capacity in the format "enabled/installed".
+ * @example
+ * Assuming an aggregation of rows where enabled capacities sum to 100 and installed capacities sum to 200
+ * "100/200"
+ *
+ * @see https://www.material-react-table.com/docs/guides/aggregation-and-grouping#custom-aggregation-functions for more information on custom aggregation functions in Material React Table.
  */
 export const capacityAggregationFn = <
   T extends ThermalClusterWithCapacity | RenewableClusterWithCapacity,
 >(): MRT_AggregationFn<T> => {
-  return (colHeader, rows) => {
+  return (_colHeader, rows) => {
     const { enabledCapacitySum, installedCapacitySum } = rows.reduce(
       (acc, row) => {
         acc.enabledCapacitySum += row.original.enabledCapacity ?? 0;

webapp/src/components/App/Singlestudy/explore/Modelization/Map/utils.ts

@@ -83,7 +83,15 @@ export const getTextColor = (bgColor: RGB): string => {
 ////////////////////////////////////////////////////////////////
 
 /**
- * Sets the graph nodes from the nodes data
+ * Custom hook to compute and return nodes with adjusted positions based on the current layer and view settings.
+ * It adjusts node positions to ensure they are correctly positioned in the graph based on the current zoom level and layer.
+ * Additionally, it calculates the color for each node, supporting layer-specific color adjustments.
+ *
+ * @param nodes Array of nodes to render.
+ * @param width Width of the rendering area.
+ * @param height Height of the rendering area.
+ * @param currentLayerId The ID of the current layer, used to adjust node positions and colors.
+ * @returns Array of nodes with updated positions and colors for rendering.
  */
 export function useRenderNodes(
   nodes: StudyMapNode[],

webapp/src/components/App/Singlestudy/explore/TableModeList/utils.ts

@@ -21,7 +21,13 @@ export interface TableTemplate<T extends TableModeType = TableModeType> {
 ////////////////////////////////////////////////////////////////
 
 /**
- * Allows to check columns validity for specified type.
+ * Allows to check columns validity for specified type. Creates a table template with unique ID, name, type, and columns configuration.
+ * This function is intended to define the structure and type of data that a table can hold.
+ *
+ * @param name The name of the table template.
+ * @param type The type of the table, determining the allowed columns and their configuration based on the table mode type.
+ * @param columns The configuration of columns specific to the table mode type.
+ * @returns A table template object including a unique ID, name, type, and columns configuration.
  */
 export function createTableTemplate<T extends TableModeType>(
   name: string,

webapp/src/components/common/GroupedDataTable/utils.ts

@@ -20,9 +20,9 @@ export interface TRow {
  * If the base value is found in the list of existing values, it appends a number
  * in the format `(n)` to the base value, incrementing `n` until a unique value is found.
  *
- * @param {string} baseValue - The original base value to check.
- * @param {string[]} existingValues - The list of existing values to check against.
- * @returns {string} A unique value.
+ * @param baseValue The original base value to check for uniqueness.
+ * @param existingValues The list of existing values to check against for duplicates.
+ * @returns A unique value derived from the base value by appending a number in parentheses, if necessary.
  */
 export const generateNextValue = (
   baseValue: string,
@@ -54,14 +54,14 @@ export const generateNextValue = (
  * based on the given original value and the existing values in tableData.
  *
  * If the property is "name", the function appends " - copy" to the original value.
- * If the property is "id", the function uses nameToId to get the base value.
+ * If the property is "id", the function uses `nameToId` to get the base value.
  *
- * This function leverages generateNextValue to ensure the uniqueness of the value.
+ * This function leverages `generateNextValue` to ensure the uniqueness of the value.
  *
- * @param {"name" | "id"} property - The property for which the unique value is generated.
- * @param {string} originalValue - The original value of the specified property.
- * @param {TRow[]} tableData - The existing table data to check against.
- * @returns {string} A unique value for the specified property.
+ * @param property The property for which the unique value is generated, either "name" or "id".
+ * @param originalValue The original value of the specified property.
+ * @param tableData The existing table data to check against for ensuring uniqueness.
+ * @returns A unique value for the specified property.
  */
 export const generateUniqueValue = (
   property: "name" | "id",

webapp/src/components/common/SplitLayoutView.tsx

@@ -8,7 +8,13 @@ interface Props {
 }
 
 /**
- * @deprecated Use SplitView instead.
+ * Renders a split layout view with a fixed left column and a flexible right column.
+ * This component is deprecated and should be replaced with the `SplitView` component for enhanced functionality and flexibility.
+ *
+ * @deprecated Use `SplitView` instead for better layout management and customization options.
+ *
+ * @param props The component props including `left` and `right` components to render in the split layout, and `sx` for styling.
+ * @returns A React component that displays a split layout with left and right sections.
  */
 function SplitLayoutView(props: Props) {
   const { left, right, sx } = props;

webapp/src/components/common/SplitView/index.tsx

@@ -11,15 +11,22 @@ export interface SplitViewProps {
 }
 
 /**
- * Renders a resizable split view layout. It can be configured
- * for both horizontal and vertical directions.
+ * Renders a resizable split view layout, configurable for both horizontal and vertical directions.
+ *
  * @see {@link SplitViewProps} for the properties it accepts.
  *
  * @example
  * <SplitView direction="vertical" sizes={[30, 70]}>
  *   <ComponentOne />
  *   <ComponentTwo />
  * </SplitView>
+ *
+ * @param props The component props.
+ * @param props.children Child components to be rendered within the split views.
+ * @param props.direction The orientation of the split view ("horizontal" or "vertical").
+ * @param props.sizes Initial sizes of each view in percentages. The array must sum to 100 and match the number of children.
+ * @param props.gutterSize The size of the gutter between split views. Defaults to 4.
+ * @returns A React component displaying a split layout view with resizable panes.
  */
 function SplitView({
   children,

webapp/src/hoc/reactHookFormSupport.tsx

@@ -67,19 +67,36 @@ export type ReactHookFormSupportProps<
       shouldUnregister?: never;
     };
 
+/**
+ * Provides React Hook Form support to a field editor component, enhancing it with form control and validation capabilities.
+ * It integrates custom validation logic, value transformation, and handles form submission state.
+ *
+ * @param options - Configuration options for the hook support.
+ * @param options.preValidate - A function that pre-validates the value before the main validation.
+ * @param options.setValueAs - A function that transforms the value before setting it into the form.
+ * @returns A function that takes a field editor component and returns a new component wrapped with React Hook Form functionality.
+ */
 function reactHookFormSupport<TValue>(
   options: ReactHookFormSupport<TValue> = {},
 ) {
   const { preValidate, setValueAs = R.identity } = options;
 
   /**
-   * Wrap in a higher component the specified field editor component
+   * Wraps the provided field editor component with React Hook Form functionality,
+   * applying the specified pre-validation and value transformation logic.
+   *
+   * @param FieldEditor - The field editor component to wrap.
+   * @returns The wrapped component with added React Hook Form support.
    */
   function wrapWithReactHookFormSupport<
     TProps extends FieldEditorProps<TValue>,
   >(FieldEditor: React.ComponentType<TProps>) {
     /**
-     * The wrapper component
+     * The wrapper component that integrates React Hook Form capabilities with the original field editor.
+     * It manages form control registration, handles value changes and blurring with custom logic, and displays validation errors.
+     *
+     * @param props - The props of the field editor, extended with React Hook Form and custom options.
+     * @returns The field editor component wrapped with React Hook Form functionality.
      */
     function ReactHookFormSupport<
       TFieldValues extends FieldValues = FieldValues,

webapp/src/hooks/useNavigateOnCondition.ts

@@ -23,18 +23,17 @@ interface UseNavigateOnConditionOptions {
 }
 
 /**
- * A React hook for conditional navigation using react-router-dom.
+ * A React hook for conditional navigation using react-router-dom. This hook allows for navigating to a different route
+ * based on custom logic encapsulated in a `shouldNavigate` function. It observes specified dependencies and triggers navigation
+ * when they change if the conditions defined in `shouldNavigate` are met.
  *
- * @function
- * @name useNavigateOnCondition
- *
- * @param {Object} options - Configuration options for the hook.
- * @param {DependencyList} options.deps - An array of dependencies that the effect will observe.
- * @param {To} options.to - The target location to navigate to, it could be a route as a string or a relative numeric location.
- * @param {function} [options.shouldNavigate] - An optional function that returns a boolean to determine whether navigation should take place.
+ * @param options - Configuration options for the hook.
+ * @param options.deps - An array of dependencies that the effect will observe.
+ * @param options.to - The target location to navigate to, which can be a route as a string or a relative numeric location.
+ * @param options.shouldNavigate - An optional function that returns a boolean to determine whether navigation should take place. Defaults to a function that always returns true.
  *
  * @example
- * - Basic usage
+ * Basic usage
  * useNavigateOnCondition({
  *   deps: [someDependency],
  *   to: '/some-route',

webapp/src/services/utils/index.ts

@@ -248,7 +248,12 @@ export const sortByName = <T extends { name: string }>(list: T[]): T[] => {
 };
 
 /**
- * @deprecated This function is deprecated. Please use nameToId instead.
+ * Converts a name string to an ID format.
+ *
+ * @deprecated Please use `nameToId` instead.
+ *
+ * @param name The string to transform.
+ * @returns The transformed ID string.
  */
 export const transformNameToId = (name: string): string => {
   let duppl = false;
@@ -290,6 +295,7 @@ export const transformNameToId = (name: string): string => {
  * Converts a name string to a valid ID string.
  * Replacing any characters that are not alphanumeric or -_,()& with a space,
  * trimming the resulting string, and converting it to lowercase.
+ *
  * @param name The name string to convert to an ID.
  * @returns The resulting ID string.
  */

webapp/src/utils/fnUtils.ts

@@ -1,6 +1,17 @@
 /**
- * Use it instead of disabling ESLint rule.
+ * A utility function designed to be used as a placeholder or stub. It can be used in situations where you might
+ * otherwise be tempted to disable an ESLint rule temporarily, such as when you need to pass a function that
+ * does nothing (for example, as a default prop in React components or as a no-operation callback).
+ *
+ * By using this function, you maintain code cleanliness and intention clarity without directly suppressing
+ * linting rules.
+ *
+ * @param args - Accepts any number of arguments of any type, but does nothing with them.
+ *
+ * @example
+ * Can be used as an empty event handler in React components
+ * <button onClick={voidFn}>Click me</button>
  */
 export function voidFn<TArgs extends unknown[]>(...args: TArgs) {
-  // Do nothing
+  // Intentionally empty, as its purpose is to do nothing.
 }

webapp/src/utils/stringUtils.ts

@@ -11,9 +11,14 @@ export const isSearchMatching = R.curry(
 );
 
 /**
- * Formats a string with values.
+ * Formats a string by replacing placeholders with specified values.
+ *
+ * @param str - The string containing placeholders in the format `{placeholder}`.
+ * @param values - An object mapping placeholders to their replacement values.
+ * @returns The formatted string with all placeholders replaced by their corresponding values.
+ *
  * @example
- * format("Hello {name}", { name: "John" }); // returns "Hello John"
+ * format("Hello {name}", { name: "John" }); // Returns: "Hello John"
  */
 export function format(str: string, values: Record<string, string>): string {
   return str.replace(/{([a-zA-Z0-9]+)}/g, (_, key) => values[key]);