# 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](https://tsdoc.org/) for documenting our TypeScript code and [TypeDoc](https://typedoc.org/) 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 `*`.

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

### Documenting Functions

```typescript
/**
 * 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

```typescript
/**
 * 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

```typescript
/**
 * 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:

```bash
yarn docs
```

This will create a `docs` directory with the generated documentation.

To watch for changes and regenerate documentation automatically:

```bash
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](https://tsdoc.org/)
- [TypeDoc Official Documentation](https://typedoc.org/)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)