frontend: write documentation for frontend functions and data structures

frontend/src/components/common/Tabs.tsx

@@ -11,15 +11,18 @@ export interface Tab {
   component: ReactNode;
 }
 
+/**
+ * Props interface for the `Tabs` component.
+ */
 export interface TabsProps {
-  tabs: Tab[];
+  tabs: Tab[]; // List of tabs to display
   tabProps?: {
     [propName: string]: any;
-  };
-  defaultIndex?: number | null | boolean;
-  onTabChanged?: (tabIndex: number) => void;
-  sx?: SxProps<Theme>;
-  ariaLabel: string;
+  }; // Optional props for the MuiTabs component
+  defaultIndex?: number | null | boolean; // Default selected tab index
+  onTabChanged?: (tabIndex: number) => void; // Callback for tab change
+  sx?: SxProps<Theme>; // Optional styles
+  ariaLabel: string; // Accessibility label for the Tabs component
 }
 
 export default function Tabs(props: TabsProps) {

frontend/src/i18n/LocaleSelect/LocaleSelect.tsx

@@ -7,14 +7,39 @@ import React from 'react';
 import { useTranslation } from 'react-i18next';
 import { supportedLanguages } from '../config';
 
+
+/**
+ * Interface for the props used by the `LocaleSelect` component, which is responsible for rendering a locale selection UI.
+ * 
+ * @param {boolean} [showTitle] - Optional flag to control whether the title of the locale selector is displayed. Defaults to `false`.
+ * @param {boolean} [showFullNames] - Optional flag to control whether to display full language names instead of language codes. Defaults to `false`.
+ * @param {FormControlProps} [formControlProps] - Optional properties to customize the `FormControl` component used for the locale selection.
+ */
 export interface LocaleSelectProps {
   showTitle?: boolean;
   showFullNames?: boolean;
   formControlProps?: FormControlProps;
 }
 
 /**
- * A UI for selecting the locale with i18next
+ * A component that provides a UI for selecting the locale with `i18next`, allowing users to switch languages in the application.
+ * It uses Material UI components such as `FormControl`, `Select`, and `MenuItem` to render a dropdown for selecting a language.
+ * 
+ * @remarks
+ * This component displays a locale selector with support for showing either the language code or the full language name, 
+ * depending on the `showFullNames` prop. It also listens for language changes via the `i18next` library and updates the UI accordingly.
+ * 
+ * @param {LocaleSelectProps} props - The properties for the `LocaleSelect` component.
+ * @param {boolean} [props.showTitle] - Optional flag to show the title of the locale selection. Defaults to `false`.
+ * @param {boolean} [props.showFullNames] - Optional flag to show the full names of the languages instead of their abbreviations. Defaults to `false`.
+ * @param {FormControlProps} [props.formControlProps] - Optional props for customizing the `FormControl` component used within the selector.
+ * 
+ * @returns {ReactNode} A `FormControl` component containing a `Select` dropdown for changing the app's language.
+ * 
+ * @example
+ * ```tsx
+ * <LocaleSelect showTitle={true} showFullNames={true} />
+ * ```
  */
 export default function LocaleSelect(props: LocaleSelectProps) {
   const { formControlProps, showFullNames } = props;

frontend/src/i18n/ThemeProviderNexti18n.tsx

@@ -4,6 +4,21 @@ import React, { ReactNode, useEffect, useState } from 'react';
 import { useTranslation } from 'react-i18next';
 import { Loader } from '../components/common';
 
+/**
+ * Returns the Material UI locale object for the given language code.
+ *
+ * @remarks
+ * This method retrieves the locale configuration for a specific language supported by
+ * Material UI. It checks the provided language code against a predefined set of available locales,
+ * and returns the corresponding locale object. If the language code is not found, it defaults to 
+ * English (`enUS`).
+ *
+ * @param locale - The language code for which the locale object is required (e.g., 'en', 'pt', 'es').
+ * 
+ * @returns The Material UI locale object corresponding to the provided language code. 
+ *          Defaults to `enUS` if the locale is not found in the predefined list.
+ */
+
 function getLocale(locale: string): typeof enUS {
   const LOCALES = {
     en: enUS,
@@ -18,8 +33,29 @@ function getLocale(locale: string): typeof enUS {
   return locale in LOCALES ? LOCALES[locale as LocalesType] : LOCALES['en'];
 }
 
-/** Like a ThemeProvider but uses reacti18next for the language selection
- *  Because Material UI is localized as well.
+/**
+ * A custom theme provider component that integrates Material UI's theme with `react-i18next` for language selection.
+ * It ensures that both the theme and language are synchronized, providing seamless localization across the application.
+ * 
+ * @remarks
+ * This component functions like a standard Material UI `ThemeProvider`, but it also listens for language changes using `react-i18next`. 
+ * When the language is changed, the corresponding Material UI locale is applied to update the theme accordingly.
+ * This is essential for supporting multiple languages and ensuring the UI behaves correctly with Right-To-Left (RTL) languages.
+ * 
+ * The component will show a loading state (`<Loader />`) until the i18n resources are ready for rendering.
+ * 
+ * @param {object} props - The properties for the component.
+ * @param {Theme} props.theme - The Material UI theme object to be applied to the app.
+ * @param {ReactNode} props.children - The child components wrapped by this theme provider.
+ * 
+ * @returns {ReactNode} The children components wrapped with the updated Material UI theme and language configurations.
+ * 
+ * @example
+ * ```tsx
+ * <ThemeProviderNexti18n theme={theme}>
+ *   <YourComponent />
+ * </ThemeProviderNexti18n>
+ * ```
  */
 const ThemeProviderNexti18n: React.FunctionComponent<{
   theme: Theme;