Documentation

Comprehensive documentation is mandatory for all code contributions. Each function and endpoint must be documented with a clear description of its purpose, a detailed specification of its input parameters (including data types and any constraints), and a precise definition of its return values (including data types and any potential error conditions).

Code Documentation

1. Comments: All code must be commented. Comments should be used to explain the purpose of the code, the logic behind it, and any assumptions or constraints.
2. Function Documentation: Each function must be documented with a clear description of its purpose, a detailed specification of its input parameters (including data types and any constraints), and a precise definition of its return values (including data types and any potential error conditions).
   • When documenting functions, we require using JSDoc syntax:

   /**
    * @function calculateSum
    * @description Calculate the sum of two numbers
    *
    * @param {Number} a First number
    * @param {Number} b Second number
    *
    * @returns {Number} Sum of a and b
    * @throws {TypeError} InvalidInput Invalid input provided
    *
    * @example calculateSum(1, 2) // 3
    */

3. Endpoint Documentation: Each endpoint must be documented with a clear description of its purpose, a detailed specification of its input parameters (including data types and any constraints), and a precise definition of its return values (including data types and any potential error conditions).
   • When documenting endpoints, we require using JSDoc syntax:

   /**
    * @endpoint {get} /api/users/:id Request User information
    * @description Get a specific user's information
    *
    * @param {Number} id Users unique ID.
    *
    * @returns {String} firstname Firstname of the User.
    * @throws {404} UserNotFound User with the given ID not found.
    *
    * @deprecated This endpoint is deprecated.
    */

API Documentation

1. API documentation should be written in Markdown format.
2. Each API endpoint must be documented with a clear description of its purpose, a detailed specification of its input parameters (including data types and any constraints), and a precise definition of its return values (including data types and any potential error conditions).
3. API documentation should be versioned and stored in the docs directory of the repository.
4. API documentation should be updated whenever a new endpoint is added, an existing endpoint is modified, or an endpoint is deprecated.