# Snowball Tools Project Documentation

## Overview

This document consolidates project standards, documentation guidelines, and best practices for the
Snowball Tools project.

## Project Purpose and Standards

### Core Principles

1. **Consistency** - Establish consistent patterns across the codebase
2. **Onboarding** - Help new developers understand project conventions
3. **Maintainability** - Make code easier to maintain and extend
4. **Quality** - Encourage best practices that lead to higher quality code

## Documentation Standards

### TSDoc and TypeDoc

We use [TSDoc](https://tsdoc.org/) for documenting TypeScript code and
[TypeDoc](https://typedoc.org/) for generating API documentation.

#### Basic Comment Structure

TSDoc comments start with `/**` and end with `*/`:

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

#### 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           |
| `@public`, `@protected`, `@private` | Visibility modifiers                      |

### Documentation 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

## Generating Documentation

Generate documentation:

```bash
yarn docs
```

Watch and regenerate documentation:

```bash
yarn docs:watch
```

## Contributing to Standards

To suggest changes or additions to project standards:

1. Discuss proposed changes with the team
2. Update the relevant documentation
3. Provide examples demonstrating the benefits of the proposed changes

## Enforcement

While these standards are not automatically enforced, developers are encouraged to follow them, and
code reviewers should check for adherence to these guidelines.

## Resources

- [TSDoc Official Documentation](https://tsdoc.org/)
- [TypeDoc Official Documentation](https://typedoc.org/)
- [TypeScript Documentation](https://www.typescriptlang.org/docs/)