Standardize JSDoc commenting across the codebase

[changeelog]

Goal

The goal of this issue is to establish a consistent and standardized way of using JSDoc comments throughout our React hooks codebase. This will improve code readability, maintainability, and make it easier for developers to understand and use the hooks effectively.

Current State

Currently, there is no consistent approach to JSDoc commenting across the React hooks codebase. Some hooks have JSDoc comments, while others don't. Additionally, the formatting and level of detail in the existing JSDoc comments vary widely.

Proposed Solution

1. Define JSDoc Guidelines for React Hooks: We should define a set of guidelines specific to documenting React hooks using JSDoc. The guidelines should cover:

• Required JSDoc tags for hooks (@param, @returns, @example, etc.)
• Formatting and style conventions for hook documentation
• Best practices for describing hook functionality, parameters, and return values
• Guidelines for providing usage examples and any necessary warnings or notes

2. Review Existing Hook JSDoc Comments: We should review the existing JSDoc comments for the React hooks in the codebase and update them to align with the defined guidelines. This will ensure consistency and completeness of the documentation.
3. Add JSDoc Comments to Undocumented Hooks: For hooks that lack JSDoc comments, we should add comprehensive comments following the defined guidelines. Each hook should have a clear description, parameter explanations, and return value documentation.
4. Provide Usage Examples: In addition to the JSDoc comments, we should provide practical usage examples for each hook. These examples should demonstrate how to use the hook in different scenarios and highlight any important considerations or best practices.
5. Automate JSDoc Generation: We can set up tools or scripts to automatically generate JSDoc documentation from the comments in the React hooks codebase. This will make it easier to maintain and access the documentation, especially as the number of hooks grows.

Discussion

Please share your thoughts, suggestions, and any concerns regarding this proposal. Let's collaborate to establish a comprehensive and developer-friendly JSDoc commenting standard for our React hooks codebase. This will greatly enhance the usability and adoption of our hooks by the React community.

[changeelog]

Hooks

/**
 * Brief description of the hook.
 *
 * A more detailed description of the hook, if necessary. Can include
 * information about when to use the hook, how it works internally,
 * or potential edge cases.
 *
 * @param {Type} name - Description of the parameter. Be specific about
 * the expected type and any constraints. If a parameter is optional,
 * indicate it using `?` after the parameter name.
 * @returns {Type} Description of the return value. Be specific about
 * the type and structure of the returned value.
 *
 * @example
 * // Example usage of the hook with explanation
 * const exampleExample = useHook(parameters);
 */
export const useHook = (parameter: Type): ReturnType => {
  // ... implementation
};

Utilities

/**
 * Brief description of the utility function.
 *
 * A more detailed description of the utility function, if necessary.
 * Can include information about when to use the function, how it works
 * internally, or potential edge cases.
 *
 * @param {Type1} parameter1 - Description of the first parameter.
 * @param {Type2} [parameter2] - Description of the second optional parameter.
 * @returns {ReturnType} Description of the return value.
 *
 * @example
 * // Example usage of the utility function
 * const result = utilityFunction(parameter1, parameter2);
 */
export const utilityFunction = (parameter1: Type1, parameter2?: Type2): ReturnType => {
  // ... implementation
};

Types

/**
 * Type description. Provide a clear and concise explanation of what
 * the type represents and how it should be used.
 *
 * @typedef {Object} TypeName
 * @property {Type} propertyName - Property description. Be specific
 * about the expected type and any constraints. Indicate optional
 * properties using `?` after the property name.
 */
export type TypeName = {
  propertyName: Type;
};

Enums

/**
 * Enum description. Explain the purpose of the enum and the meaning
 * of each value.
 *
 * @enum {string} EnumName
 */
export enum EnumName {
  /** Description of value 1. */
  VALUE1 = 'value1',
  /** Description of value 2. */
  VALUE2 = 'value2',
}

Interfaces

/**
 * Interface description. Provide a clear and concise explanation of
 * what the interface represents and how it should be used.
 *
 * @interface InterfaceName
 */
export interface InterfaceName {
  /** Description of property 1. */
  property1: Type;
  /** Description of property 2. (Optional) */
  property2?: Type;
}

Constants

/**
 * Constant description. Explain the purpose and usage of the constant.
 *
 * @type {Type}
 */
export const CONSTANT_NAME: Type = value;

[changeelog]

Updated the documentation pattern for hooks
UPD: Updated the documentation pattern for types? enums, interfaces, constants.
UPD: Added Utilities documentation pattern.

[changeelog]

I think I've covered most of the cases in this issues and there will be no problems with it in the future. There is no need for this issue anymore.