laconic-deploy/DOCUMENTATION.md

Documentation Guide for Snowball Tools

This guide explains how to write and generate documentation for the Snowball Tools project.

TSDoc and TypeDoc

We use TSDoc for documenting our TypeScript code and TypeDoc for generating API documentation from those comments.

Writing Documentation

Basic Comment Structure

TSDoc comments start with /** and end with */. Each line within the comment block typically starts with a *.

/**
 * This is a TSDoc comment.
 */

Documenting Functions

/**
 * Calculates the sum of two numbers.
 * 
 * @param a - The first number
 * @param b - The second number
 * @returns The sum of a and b
 * 
 * @example
 * ```ts
 * const result = add(1, 2);
 * console.log(result); // 3
 * ```
 */
function add(a: number, b: number): number {
  return a + b;
}

Documenting Classes

/**
 * Represents a user in the system.
 * 
 * @remarks
 * This class is used throughout the application to represent user data.
 * 
 * @example
 * ```ts
 * const user = new User('John', 'Doe');
 * console.log(user.fullName); // "John Doe"
 * ```
 */
class User {
  /**
   * Creates a new User instance.
   * 
   * @param firstName - The user's first name
   * @param lastName - The user's last name
   */
  constructor(
    /** The user's first name */
    public firstName: string,
    /** The user's last name */
    public lastName: string
  ) {}

  /**
   * Gets the user's full name.
   */
  get fullName(): string {
    return `${this.firstName} ${this.lastName}`;
  }
}

Documenting Interfaces

/**
 * Configuration options for the application.
 * 
 * @public
 */
interface AppConfig {
  /**
   * The port number the server should listen on.
   * @default 3000
   */
  port: number;
  
  /**
   * The host the server should bind to.
   * @default "localhost"
   */
  host: string;
  
  /**
   * Whether to enable debug mode.
   * @default false
   */
  debug?: boolean;
}

Common TSDoc Tags

Tag	Description
@param	Documents a function parameter
@returns	Documents the return value
@throws	Documents exceptions that might be thrown
@example	Provides an example of usage
@remarks	Adds additional information
@deprecated	Marks an item as deprecated
@see	Refers to related documentation
@default	Documents the default value
@public, @protected, @private	Visibility modifiers
@internal	Marks an item as internal (not part of the public API)
@beta	Marks an item as in beta stage
@alpha	Marks an item as in alpha stage
@experimental	Marks an item as experimental

Generating Documentation

To generate documentation for the project, run:

yarn docs

This will create a docs directory with the generated documentation.

To watch for changes and regenerate documentation automatically:

yarn docs:watch

Best Practices

1. Document Public APIs: Always document public APIs thoroughly.
2. Include Examples: Provide examples for complex functions or classes.
3. Be Concise: Keep documentation clear and to the point.
4. Use Proper Grammar: Use proper grammar and punctuation.
5. Update Documentation: Keep documentation in sync with code changes.
6. Document Parameters: Document all parameters, including their types and purpose.
7. Document Return Values: Document what a function returns.
8. Document Exceptions: Document any exceptions that might be thrown.

Example Files

For reference, check out these example files that demonstrate proper TSDoc usage:

• packages/backend/src/utils/tsdoc-example.ts
• packages/frontend/src/utils/tsdoc-example.ts

Resources

• TSDoc Official Documentation
• TypeDoc Official Documentation
• TypeScript Documentation