Unify documentation rules across languages and fix the Python template
Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Jan Doubravský
co-authored by
Claude Opus 5
Claude Opus 5
parent
19e9b8f2fa
commit
5c0f2f758f
+34
-14
@@ -14,11 +14,20 @@
|
||||
- **PROJECT.md** — Project goals and current state
|
||||
- **CHANGELOG.md** — Version history
|
||||
|
||||
### Documentation Organization
|
||||
|
||||
All detailed documentation of features and systems belongs in the `docs/` folder, not in the project root.
|
||||
|
||||
The API reference is generated by `cargo doc` from doc comments — `docs/` holds the prose documentation that does not fit in doc comments.
|
||||
|
||||
The root directory contains only the core documents: `README.md`, `AGENTS.md`, `DESIGN_DOCUMENT_LIB.md`, `PROJECT.md`, `CHANGELOG.md`.
|
||||
|
||||
---
|
||||
|
||||
## 1. Code Style
|
||||
|
||||
- **Rust edition:** 2021
|
||||
- **Rust edition:** 2024 (requires Rust 1.85 or newer)
|
||||
- Declare the minimum toolchain in `Cargo.toml` (`rust-version = "1.85"`) so consumers get a clear error instead of a compile failure
|
||||
- Format with **rustfmt** — run `cargo fmt` before every commit
|
||||
- Lint with **clippy** — run `cargo clippy -- -D warnings` before every commit
|
||||
- **snake_case** functions/variables/modules, **PascalCase** types/traits, **SCREAMING_SNAKE_CASE** constants
|
||||
@@ -43,7 +52,7 @@ Never edit `Cargo.toml` dependency versions by hand — use `cargo add`.
|
||||
|
||||
---
|
||||
|
||||
## 2. Project Structure
|
||||
## 3. Project Structure
|
||||
|
||||
```
|
||||
project/
|
||||
@@ -54,6 +63,7 @@ project/
|
||||
│ └── mod.rs
|
||||
├── tests/ # Integration tests (test the public API only)
|
||||
├── examples/ # Usage examples
|
||||
├── docs/ # Detailed documentation
|
||||
├── Cargo.toml
|
||||
└── Cargo.lock # Do NOT commit — add to .gitignore
|
||||
```
|
||||
@@ -62,7 +72,7 @@ No `main.rs` — libraries have no entry point.
|
||||
|
||||
---
|
||||
|
||||
## 3. Public API
|
||||
## 4. Public API
|
||||
|
||||
- Everything intended for external use must be `pub` and re-exported from `lib.rs`
|
||||
- Use `pub(crate)` for internal items that cross module boundaries
|
||||
@@ -79,7 +89,7 @@ pub use types::{Config, Response};
|
||||
|
||||
---
|
||||
|
||||
## 4. Error Handling
|
||||
## 5. Error Handling
|
||||
|
||||
- Define all public error types in `src/error.rs` using **thiserror**
|
||||
- Export all errors from `lib.rs`
|
||||
@@ -101,7 +111,7 @@ pub enum MyError {
|
||||
|
||||
---
|
||||
|
||||
## 5. Logging
|
||||
## 6. Logging
|
||||
|
||||
This is a library. Libraries must **never configure logging sinks** — that is the responsibility of the consuming application.
|
||||
|
||||
@@ -134,13 +144,13 @@ Never call `tracing_subscriber::fmt().init()` or any sink setup inside library c
|
||||
|
||||
---
|
||||
|
||||
## 6. Environment and Secrets
|
||||
## 7. Environment and Secrets
|
||||
|
||||
Libraries do not read environment variables or `.env` files. Configuration is passed by the caller via arguments or constructor parameters.
|
||||
|
||||
---
|
||||
|
||||
## 7. Testing
|
||||
## 8. Testing
|
||||
|
||||
- Use Rust's built-in test framework — `#[test]` and `#[cfg(test)]`
|
||||
- Unit tests live in the same file as the code, in a `mod tests` block
|
||||
@@ -163,7 +173,7 @@ mod tests {
|
||||
|
||||
---
|
||||
|
||||
## 8. Documentation
|
||||
## 9. Documentation
|
||||
|
||||
All public items must have doc comments. Use `cargo doc --open` to verify locally.
|
||||
|
||||
@@ -187,7 +197,7 @@ pub fn parse(s: &str) -> Result<u32, MyError> { ... }
|
||||
|
||||
---
|
||||
|
||||
## 9. Tooling
|
||||
## 10. Tooling
|
||||
|
||||
| Tool | Purpose |
|
||||
|------|---------|
|
||||
@@ -205,7 +215,7 @@ cargo test
|
||||
|
||||
---
|
||||
|
||||
## 10. Distribution
|
||||
## 11. Distribution
|
||||
|
||||
Build and publish with Cargo:
|
||||
|
||||
@@ -218,7 +228,7 @@ cargo publish # Publish to crates.io (requires login)
|
||||
|
||||
---
|
||||
|
||||
## 11. Versioning
|
||||
## 12. Versioning
|
||||
|
||||
- Follow **semantic versioning**: `MAJOR.MINOR.PATCH`
|
||||
- Version is defined in `Cargo.toml` under `[package]`
|
||||
@@ -228,14 +238,24 @@ cargo publish # Publish to crates.io (requires login)
|
||||
|
||||
---
|
||||
|
||||
## 12. Documentation and Task Management
|
||||
## 13. Documentation and Task Management
|
||||
|
||||
- Keep `PROJECT.md` and `CHANGELOG.md` up to date when making changes
|
||||
- Document architectural changes in this file or in `docs/`
|
||||
- `README.md` must contain installation instructions and usage examples for the public API
|
||||
|
||||
### Task notation
|
||||
|
||||
Tasks are written as single-line comments directly in code, using the **Todo Tree** tags defined in `AGENTS.md` (`TODO`, `FIXME`, `BUG`, `HACK`, `NOTE`). `PROJECT.md` carries only cross-cutting tasks that have no single place in the code.
|
||||
|
||||
```rust
|
||||
// TODO: one-liner description of a task to be done
|
||||
// FIXME: one-liner description of a known bug to be fixed
|
||||
// TODO: extract this into a separate module
|
||||
// FIXME: panics on an empty slice
|
||||
// BUG: off-by-one when the buffer is exactly full
|
||||
// HACK: temporary workaround until the crate adds paging
|
||||
// NOTE: order matters here, the parser is stateful
|
||||
```
|
||||
|
||||
No other task format is used — **no checkboxes, no numbered lists in documentation**.
|
||||
|
||||
If a tag already exists at a specific location in code, do not repeat it in `PROJECT.md`.
|
||||
|
||||
Reference in New Issue
Block a user