Skip to content

3. Documentation Guidelines

Jump to bottom
Jarno Seppänen edited this page Jun 10, 2026 · 3 revisions

Documentation Guidelines for the Altzone-WebPages Project

As part of the Altzone-WebPages project, We strongly encourage all team members to consistently document their code, with particular emphasis on documenting complex sections. Writing clear documentation is crucial for maintaining a codebase that is understandable, maintainable, and easy to collaborate on.

To facilitate this, we will be using JSDoc for documenting our TypeScript code and Storybook for documenting our React components. Below is a breakdown of the guidelines and tools we will use:

1. JSDoc for TypeScript Documentation

Purpose:

JSDoc is an essential tool for documenting JavaScript and TypeScript code directly within the codebase. Using JSDoc, we generate API documentation that provides detailed information on how to use our project's functions, classes, interfaces, and methods. This documentation makes the codebase easier to understand, maintain, and extend for developers.

Guidelines:

1. Comment Style

Use JSDoc comment blocks (/** ... */) to document functions, classes, interfaces, types, and any complex logic. Place these comments directly above the relevant code, providing clear explanations about the purpose and functionality of the code. Consistency is key, as it ensures that documentation across the project follows the same structure.

2. Type Annotations

Since TypeScript already includes type annotations, JSDoc comments should enhance and complement these types. JSDoc is particularly useful for explaining how and why specific types are used, providing additional context that helps developers understand the intent behind each type annotation. Avoid using JSDoc to redefine types already defined by TypeScript.

3. Required Tags

In JSDoc comments, use tags to specify essential information about the function, class, or interface. These tags help standardize the format of documentation and provide crucial details at a glance:

  • @param – Describes the parameters of a function, including their names and types.
  • @returns – Describes the return value of a function, including its type and purpose.
  • @template – Used to document generic types in functions or classes, allowing developers to specify that a function or class can operate on any data type. This is especially helpful for generic or polymorphic functions.
  • @throws – Explains any exceptions or errors that may be thrown by a function, especially if the function performs input validation or other checks.
Example Using @template:
/**
 * Creates an array with repeated instances of a given item.
 *
 * @template T - The type of the item to repeat.
 * @param {T} item - The item to repeat in the array.
 * @param {number} count - The number of repetitions.
 * @returns {T[]} An array containing the repeated item.
 */
function repeat<T>(item: T, count: number): T[] {
    return Array(count).fill(item);
}
Example Using Multiple Tags:
/**
 * Calculates the area of a circle.
 *
 * @param {number} radius - The radius of the circle.
 * @returns {number} The area of the circle.
 * @throws {Error} Throws an error if the radius is negative.
 */
function calculateArea(radius: number): number {
    if (radius < 0) throw new Error('Radius cannot be negative');
    return Math.PI * radius * radius;
}

4. Examples

Including examples in JSDoc comments is strongly recommended, especially for more complex functions and classes. Examples demonstrate usage and provide a clear context for expected inputs and outputs. Use @example blocks within JSDoc comments to provide these code samples, ensuring they are concise and relevant.

Example of Using JSDoc with a React Component
/**
 * A React functional component that renders a pie chart with customizable attributes.
 *
 * @param {Props} props - The properties passed to the component.
 * @returns {JSX.Element} A JSX element representing the pie chart wrapped in a div container.
 *
 * @example
 * ```typescript jsx
 * const defaultSlice = {
 *   max: 100,
 *   sections: [
 *     { value: 50, color: '#ff0000' },
 *     { value: 50, color: '#00ff00' }
 *   ]
 * };
 *
 * const upgradeSlice = {
 *   max: 200,
 *   sections: [
 *     { value: 100, color: '#0000ff' },
 *     { value: 100, color: '#ffff00' }
 *   ]
 * };
 *
 * <AttributesPie
 *   characterDefault={defaultSlice}
 *   characterUpgrade={upgradeSlice}
 *   borderwidth={5}
 *   bordercolor="#000000"
 *   radius={100}
 * />
 */
export const AttributesPie = (props: Props): JSX.Element => { /* component logic */ };
Documenting Interfaces

When documenting components that use complex properties, it’s essential to describe each property in detail within the associated interface. This approach provides developers with a clear understanding of the properties, their types, and intended uses. Here’s an example of documenting an interface for properties related to a pie chart component:

/**
 * Interface representing properties for pie chart slices.
 *
 * @interface Props
 *
 * @property {SliceState} characterDefault - The properties for the default state of the pie slice.
 * @property {SliceState} characterUpgrade - The properties for the upgraded state of the pie slice.
 * @property {number} borderwidth - The width of the border for the pie slice.
 * @property {string} bordercolor - The color of the border for the pie slice.
 * @property {number} radius - The radius of the pie slice.
 */
interface Props {
    characterDefault: SliceState;
    characterUpgrade: SliceState;
    borderwidth: number;
    bordercolor: string;
    radius: number;
}

/**
 * Interface representing the properties for a section of a pie chart.
 *
 * @interface PieSection
 *
 * @property {number} value - The numerical value that the pie section represents.
 * @property {string} color - The color associated with the pie section in hexadecimal, RGB, or named color formats.
 */
interface PieSection {
    value: number;
    color: string;
}

/**
 * Interface representing the properties for a pie slice.
 *
 * @interface SliceState
 * @property {number} max - The maximum value of the pie slice.
 * @property {Array<PieSection>} sections - An array of section properties for the pie slice.
 */
interface SliceState {
    max: number;
    sections: Array<PieSection>;
}

Resources:

3. General Documentation Best Practices

  • Consistency: Follow the same style and conventions across the entire project to ensure uniformity in the documentation.
  • Clarity: Write documentation with the reader in mind. Avoid jargon and ensure that explanations are clear and concise.
  • Version Control: Keep the documentation up-to-date with the codebase. Ensure that any changes to the code are reflected in the documentation.

By adhering to these guidelines, we will build a robust documentation system that supports both current and future developers working on the Altzone-WebPages project.

Clone this wiki locally