Petr Polezhaev
2ab41ead9f
- docs/overview.md: rewrite for current architecture (src/ layout, split JS/CSS modules, credentials/models/functions/ui config categories, correct test fixture targets) - docs/contributing.md: new — documentation philosophy and style guide - AGENTS.md: add rule to follow docs/contributing.md
58 lines
2.1 KiB
Markdown
58 lines
2.1 KiB
Markdown
# Documentation Standards
|
|
|
|
## Philosophy
|
|
Prefer self-documenting code and in-code comments over external documentation.
|
|
Write external docs only when the information cannot live closer to the code.
|
|
|
|
## What belongs where
|
|
|
|
| Content | Where |
|
|
|---------|-------|
|
|
| Why a function does something non-obvious | Inline comment at the relevant line |
|
|
| Contract, parameters, exceptions | Docstring on the function |
|
|
| Module purpose, dependencies, exports | File header comment |
|
|
| Architecture, data flow, system-level decisions | `docs/overview.md` |
|
|
| Setup, configuration, usage for humans | `README.md` |
|
|
| Agent/AI session rules | `AGENTS.md` |
|
|
|
|
## Style
|
|
- Brief and technical. No preambles, no summaries, no filler.
|
|
- No emojis.
|
|
- High-level overview only in external docs — implementation details belong in code.
|
|
- Present tense, imperative mood for instructions.
|
|
|
|
## Python docstrings
|
|
All public functions use Google style: one-line summary, then `Args:`, `Returns:`, `Raises:` sections if non-trivial. List every domain exception the function can raise directly or via propagation.
|
|
|
|
```python
|
|
def crop_save(src: Path, dst: Path, box: tuple[int, int, int, int]) -> None:
|
|
"""Crop src image to box and write to dst, overwriting if present.
|
|
|
|
Args:
|
|
src: Source image path.
|
|
dst: Destination path; parent directory must exist.
|
|
box: (x, y, w, h) in pixels.
|
|
|
|
Raises:
|
|
FileNotFoundError: If src does not exist.
|
|
"""
|
|
```
|
|
|
|
## JS file headers
|
|
Every JS file starts with a block comment stating: purpose, dependencies (Depends on:), exports (Provides:).
|
|
|
|
```js
|
|
/*
|
|
* helpers.js
|
|
* Pure utility functions with no dependencies on other application modules.
|
|
*
|
|
* Provides: esc(), toast(), isDesktop()
|
|
*/
|
|
```
|
|
|
|
## When NOT to document
|
|
- Do not add docstrings or comments to code you did not change.
|
|
- Do not document implementation details that are already clear from the code.
|
|
- Do not keep comments that describe what the code does when the code already says it clearly.
|
|
- Do not update `docs/overview.md` for implementation details — only for structural/architectural changes.
|