From cfb7b7c83cfb862bfc9824e524ce4be6b3dfcc50 Mon Sep 17 00:00:00 2001 From: Serkyo Date: Sun, 10 May 2026 22:04:23 +0200 Subject: [PATCH] docs(workspace): update project rules for formal documentation and struct field docstrings --- AGENTS.md | 11 ++++++++++- CLAUDE.md | 11 ++++++++++- 2 files changed, 20 insertions(+), 2 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index edeca8d..ddfe238 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,7 +105,7 @@ Then follow this loop on every step: 1. **Verify** the user's claimed change is actually present and correct. 2. If wrong or incomplete, explain what's off and let them fix it — do not silently patch it yourself. -3. Once correct, **ensure useful comments are added** before committing. This includes function doc comments (`///`) and inline comments above important parts of the logic. If they are missing, add them yourself and try to follow the style of the existing comments in the codebase. +3. Once correct, **ensure useful comments are added** before committing. This includes function doc comments (`///`) and inline comments above important parts of the logic. If they are missing, add them yourself and follow the documention style specified in the relevant section below. 4. After comments are verified, **create a git commit** capturing that step (following the commit conventions above) before moving on. 5. **Then** tell the user what to do next. @@ -128,6 +128,15 @@ The game is **multithreaded by design** — single-threaded would not meet the p - **Errors in binaries** (`client`, `server`): [`anyhow`](https://docs.rs/anyhow/) at the top level, with `.context("...")` for human-readable layering. Library errors compose into `anyhow::Error` cleanly via `?`. - **Never `.unwrap()` or `.expect()` outside `main` / setup / tests**, except where the invariant is genuinely impossible to violate. In the hot path, propagate with `?` and let the caller decide. +## Documentation style + +- **Objective Tone:** All comments (both doc comments `///` and inline `//`) must be written in a formal, objective, and neutral tone. +- **No Personal Pronouns:** Avoid first-person ("we", "our", "us") or second-person ("you", "your") pronouns. +- **Voice:** Use the passive voice or neutral descriptive language. Instead of "We initialize the buffer," use "The buffer is initialized." Instead of "Your vertex shader needs this," use "The vertex shader requires this." +- **Focus:** Describe the code's behavior, the system's state, or technical invariants. +- **Struct Documentation:** Every field in a public or internal struct must have a doc comment (`///`) explaining its purpose and any invariants. +- **Stability:** Treat the documentation as a technical specification for the engine. + ## Target platforms **Linux and Windows only.** No macOS, no mobile, no console, no web/WASM. diff --git a/CLAUDE.md b/CLAUDE.md index 15d3cef..eca6fad 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -105,7 +105,7 @@ Then follow this loop on every step: 1. **Verify** the user's claimed change is actually present and correct. 2. If wrong or incomplete, explain what's off and let them fix it — do not silently patch it yourself. -3. Once correct, **ensure useful comments are added** before committing. This includes function doc comments (`///`) and inline comments above important parts of the logic. If they are missing, add them yourself and try to follow the style of the existing comments in the codebase. +3. Once correct, **ensure useful comments are added** before committing. This includes function doc comments (`///`) and inline comments above important parts of the logic. If they are missing, add them yourself and follow the documention style specified in the relevant section below. 4. After comments are verified, **create a git commit** capturing that step (following the commit conventions above) before moving on. 5. **Then** tell the user what to do next. @@ -128,6 +128,15 @@ The game is **multithreaded by design** — single-threaded would not meet the p - **Errors in binaries** (`client`, `server`): [`anyhow`](https://docs.rs/anyhow/) at the top level, with `.context("...")` for human-readable layering. Library errors compose into `anyhow::Error` cleanly via `?`. - **Never `.unwrap()` or `.expect()` outside `main` / setup / tests**, except where the invariant is genuinely impossible to violate. In the hot path, propagate with `?` and let the caller decide. +## Documentation style + +- **Objective Tone:** All comments (both doc comments `///` and inline `//`) must be written in a formal, objective, and neutral tone. +- **No Personal Pronouns:** Avoid first-person ("we", "our", "us") or second-person ("you", "your") pronouns. +- **Voice:** Use the passive voice or neutral descriptive language. Instead of "We initialize the buffer," use "The buffer is initialized." Instead of "Your vertex shader needs this," use "The vertex shader requires this." +- **Focus:** Describe the code's behavior, the system's state, or technical invariants. +- **Struct Documentation:** Every field in a public or internal struct must have a doc comment (`///`) explaining its purpose and any invariants. +- **Stability:** Treat the documentation as a technical specification for the engine. + ## Target platforms **Linux and Windows only.** No macOS, no mobile, no console, no web/WASM.