forked from cerc-io/snowballtools-base
e1c2a8ce2c
This commit introduces a comprehensive documentation strategy for the project, focusing on: - Centralizing routing configuration - Adding detailed documentation for frontend architecture - Creating standards for component documentation - Implementing a feature building process template - Removing legacy documentation files Key changes include: - Added routing strategy and implementation documents - Created project-wide documentation standards - Introduced new documentation structure in qwrk-docs - Removed redundant README and documentation files - Enhanced routing and layout documentation
90 lines
3.0 KiB
Markdown
90 lines
3.0 KiB
Markdown
# 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/)
|