|
| 1 | +--- |
| 2 | +sidebar_position: 1 |
| 3 | +--- |
| 4 | + |
| 5 | +# Component documentation |
| 6 | + |
| 7 | +**Audience:** Bitwarden engineers and AI agents writing or consuming in-repo documentation. |
| 8 | + |
| 9 | +Notation follows the [documentation standard's Notation](./index.md#notation). These requirements |
| 10 | +hold for every repo for as long as it lives, enforced by review and the doc-currency plugin. New |
| 11 | +repositories satisfy them at initialization by starting from |
| 12 | +[bitwarden/template](https://github.com/bitwarden/template). Existing repos converge per |
| 13 | +[Changes to this standard](./index.md#changes-to-this-standard). Additional local guidance MAY be |
| 14 | +layered on top, as each situation dictates. |
| 15 | + |
| 16 | +Any component that other engineers or agents consume (that is, it exposes a public interface) MUST |
| 17 | +have an **entry point for its scope's documentation**, at every scope from a single component to the |
| 18 | +repo root. The entry point lives where the component's ecosystem surfaces documentation: |
| 19 | + |
| 20 | +- At **component scope**, the entry point is the `README.md`, which registries render for packaged |
| 21 | + components (a crate, an npm package, a NuGet project). Rust crates keep the README and the rustdoc |
| 22 | + landing page one artifact with `#![doc = include_str!("../README.md")]`. |
| 23 | +- **Below component scope**, the entry point is the language's module-level documentation where it |
| 24 | + exists (`//!` in Rust), since a README there duplicates what the toolchain already owns and no |
| 25 | + tooling surfaces it. It SHOULD be lint-enforced where the language supports it (Rust's |
| 26 | + `missing_docs`). |
| 27 | +- At **container and system scopes** (a container grouping several components, the repo root), the |
| 28 | + entry point is a `README.md`, since no language ecosystem claims them. |
| 29 | + |
| 30 | +Whatever its carrier, the entry point MUST contain: |
| 31 | + |
| 32 | +1. **Purpose:** what problem this component solves, in 1–3 sentences. |
| 33 | +2. **Key concepts:** the domain model or invariants a consumer must know (e.g., `libs/state`'s |
| 34 | + data-loss warning on key renames; `bitwarden-crypto`'s `derive_`/`make_` naming rules). |
| 35 | +3. **Usage:** the primary entry points, with a short code sample where the API is not self-evident. |
| 36 | +4. **Gotchas / constraints:** the things that bite people (e.g., `libs/auth`'s "do not add new code |
| 37 | + here" notice). This section MUST exist when such constraints do and MUST NOT exist when they do |
| 38 | + not. |
| 39 | + |
| 40 | +Documentation grows outward from the entry point of the |
| 41 | +[lowest common ancestor](./index.md#where-documentation-lives-rules-1-2) of the code it describes. A |
| 42 | +guide spanning several components therefore belongs to their parent scope: |
| 43 | + |
| 44 | +1. Everything starts at the scope's entry point. |
| 45 | +2. A single topic that deserves its own document becomes a named `.md` next to the code it |
| 46 | + describes, linked from the entry point (`apps/browser/src/autofill/lifecycle.design.md` is the |
| 47 | + exemplar). |
| 48 | +3. When the scope's documentation outgrows this, it splits into a `docs/` folder (exactly that name, |
| 49 | + lowercase) at the scope root. `docs/` exists only beside the entry point it extends: at the repo |
| 50 | + root (`clients/docs/cipher-types.md` is the exemplar) or a component with its own entry point |
| 51 | + (`util/Seeder/Seeds/docs/`), never an arbitrary subdirectory. |
| 52 | + |
| 53 | +Scopes layer and multiple perspectives exist. A parent scope's documentation MAY describe the same |
| 54 | +code at a higher altitude, sanding off detail the deeper docs own and linking down to them, and the |
| 55 | +same subject MAY be documented separately per audience. Both are approved. Duplication is two |
| 56 | +artifacts sharing one perspective. |
| 57 | + |
| 58 | +Below component scope, reference documentation is code: doc comments on public symbols, reviewed and |
| 59 | +merged with functionality, lint-enforced where the platform supports it. Doc comments MUST follow |
| 60 | +the language's documentation norms for structure and detail. Where not enforced by the type system, |
| 61 | +doc comments MUST say what a caller needs (behavior, invariants, error cases). Repos with doc CI |
| 62 | +SHOULD fail the build on broken docs (the `sdk-internal` `cargo doc -D warnings` pattern). |
0 commit comments