Code documentation (Google style)
This page explains how to document code in Bookclerk: the rules every language follows, the quality bar, the per-language formats, and the checks CI runs.
Bookclerk uses Google-style inline API documentation, so each language
can generate a browsable reference. The published docs carry it as
Markdown beside the hand-written pages: the plugin SDKs under
plugins/sdk/, the Web API under server/api/,
the other crates under internals/crates/ and the UI library under
contributing/ui/ (see
docs publishing). Generate the HTML
locally with:
./scripts/generate-api-docs.sh
CI runs the same script, and the docs must build cleanly.
- Product docs stay in this
docs/tree. - API reference HTML is generated into
target/api-docs/{rust,typescript,python,ui}/, outsidedocs/; CI doesn't keep it, so regenerate it locally.
- crates.io and docs.rs: the guest SDK crates
(
bookclerk-plugin-sdk,bookclerk-plugin-abi,bookclerk-plugin-manifest) render from rustdoc. - npm and PyPI:
@bookclerk/plugin-sdk(TypeDoc) andbookclerk-plugin-sdk(pdoc) mirror the same contract. - Contributors: public items can be found without reading call sites.
- Document every item that Clippy's documentation lints cover:
- Public items (modules, types, fields, variants, functions,
methods, constants, traits), through rustc
missing_docs. - Private items (including fields of private types and enum-variant
fields), through Clippy
missing_docs_in_private_items. It is a workspace lint, and CI promotes warnings to errors withRUSTFLAGS=-D warnings.
- Public items (modules, types, fields, variants, functions,
methods, constants, traits), through rustc
- Start with a one-sentence summary in the third person (not "This function…").
- Follow it with details, then the language's own sections for arguments, returns, errors or throws, and examples when useful.
- Prefer links to product docs (
docs/plugins/README.md, ADRs) over repeating architecture essays in every item. - Generated projections (SeaORM
entities/*field mirrors, the ABI'sgenerated.tsandabi.pysynced from the schema) still get field-level summaries. Generators should emit or keep comments when they can. - Don't leave
#![allow(missing_docs)]on publish surfaces. A narrow#[allow(missing_docs)]or#[allow(clippy::missing_docs_in_private_items)]is only for vendored or machine-generated code that can't carry comments (such as protobuf).
Generated docs must be readable by people. Reject stubs that echo the identifier:
| Bad (don't ship) | Good |
|---|---|
/// Cache dir. |
/// Absolute path to the guest download cache for this fetch. |
/// Message variant. |
/// Operator-facing error text with no structured code. |
/// Path. |
/// Filesystem path from host params (jail-granted). |
/** Force. */ |
/** When true, overwrite an existing credential blob. */ |
The minimum for each kind of item:
- Types, fields and variants. Explain the purpose, units and
invariants, and how the value is used, not just the name again. Mention
wire names (
camelCase) when they differ from the Rust identifiers. - Functions and methods. Include
# Arguments,# Returnsand# Errors(or JSDoc@param,@returns,@throws, or GoogleArgs,Returns,Raises) for anything more than a trivial getter. - Modules and crates. State the audience (guest author or host), the feature flags, and links to product docs or examples.
- Examples. Prefer a short
# Examplesor@exampleon entry-point APIs (PluginWorker,parse,serve, CLI helpers). CI compiles every rustdoc example (cargo test --doc). Crates without runnable examples reportrunning 0 tests, and that isn't a skipped check.
Note
CI checks only that sections and tags exist: Clippy
missing_errors_doc and missing_panics_doc on public Rust items,
Oxlint require-param and require-returns on TypeScript API surfaces,
and Ruff Google D rules on the Python SDK. Whether the description is
more than a stub is for review. Publish crates also run those Clippy
section lints on private items, through clippy-publish/clippy.toml
(check-private-items = true).
Map the Google API sections onto rustdoc Markdown:
/// Brief summary ending with a period.
///
/// Optional longer description of behavior, invariants, and when to call this.
///
/// # Arguments
///
/// * `path` - Absolute path to the guest install directory.
/// * `policy` - Egress policy already approved by the operator.
///
/// # Returns
///
/// Describe metadata including negotiated `api_version`.
///
/// # Errors
///
/// Returns [`SdkError::Protocol`] when the guest speaks an unsupported version.
///
/// # Examples
///
/// ```
/// # use bookclerk_plugin_sdk::PluginWorker;
/// // ...
/// ```
| Item | Required |
|---|---|
Crate or module (//!) |
Purpose, audience (host or guest), links to related docs |
pub struct / enum / trait |
A summary, plus field and variant docs |
| Private items | A one-sentence summary (Clippy missing_docs_in_private_items) |
pub fn and methods |
A summary; # Arguments / # Returns / # Errors when not obvious |
| Feature-gated items | The feature name (db, tools, …) |
The workspace lints are missing_docs = "warn" and
clippy::missing_docs_in_private_items = "warn", and CI promotes warnings
to errors with RUSTFLAGS="-D warnings".
- Publish-oriented crates also set
[package.metadata.docs.rs], so docs.rs builds all features. - Publish-crate CI sets
CLIPPY_CONF_DIR=clippy-publish(check-private-items = true), so the# Errorsand# PanicsClippy denies cover private items there too.
Structural documentation is enforced automatically. Whether the prose is useful stays a review responsibility (see GitHub issue #157).
| Surface | Tooling |
|---|---|
Rust missing_docs |
Workspace lint + RUSTFLAGS=-D warnings |
| Rust private docs | Workspace clippy::missing_docs_in_private_items + RUSTFLAGS=-D warnings |
| Rustdoc HTML and links | ./scripts/generate-api-docs.sh (see below) |
| Rust doctests | cargo test --doc (see below) |
| Publish-crate Clippy docs | missing_errors_doc / missing_panics_doc on the ABI, manifest and SDK crates, including private items (CLIPPY_CONF_DIR=clippy-publish) |
| Rust public section shape | The same Errors/Panics Clippy denies on selected packages (existence only) |
| TypeScript JSDoc shape | Oxlint: @param / @returns existence on API surfaces (ui/src/lib/**, packages/plugin-sdk/src/**); description rules off |
| TypeDoc exports | validation.notDocumented + invalidLink with treatValidationWarningsAsErrors |
| Python Google docstrings | Ruff D rules with lint.pydocstyle.convention = "google" (section shape only) |
| UI smoke | npm run lint + npm run test:safe-html when the UI is affected |
| CLI reference | cli_reference_is_current in bookclerk-cli (see below) |
| Web API reference | the_committed_document_is_current and the_committed_v30_document_is_current in bookclerkd (see below) |
| Rust doc comment file links | python3 scripts/tests/test_docs_markdown.py (no relative file links in library doc comments; see docs publishing) |
| Private-docs regression | python3 scripts/tests/test_private_docs_lint.py (every workspace package has [lints] workspace = true) |
Some of these need more than a cell:
- Rustdoc HTML and links. The script denies broken, private and redundant intra-doc links, plus invalid HTML, URLs and code blocks. Publish crates also deny missing crate-level docs.
- Rust doctests.
cargo test --docruns for every library on the full suite (selected packages when selective CI is on). Most crates have zero runnable# Examples, and that is expected. Behavioral coverage is theTeststep (--tests: library and binary unit tests, plus integration tests). - CLI reference. The test fails when
the CLI reference no longer matches the
clap definitions. Regenerate it with
UPDATE_CLI_REFERENCE=1 cargo test -p bookclerk-cli cli_reference. - Web API reference. The tests fail when
crates/bookclerkd/openapi.json(OpenAPI 3.1) or its OpenAPI 3.0 copycrates/bookclerkd/openapi-3.0.jsonno longer matches the routes. Regenerate them withcargo run -p bookclerkd -- --print-openapi > crates/bookclerkd/openapi.jsonandcargo run -p bookclerkd -- --print-openapi 3.0 > crates/bookclerkd/openapi-3.0.json. Sibling tests keep the document complete: every JSON body names a schema (json_bodies_are_typed), every schema property, nested objects andoneOf/allOfbranches included, carries anexampleunless it is composed of other schemas or a one-valueenum(every_property_carries_an_example), every response outside the 2xx range shows its body (error_responses_carry_an_example) and every route that reads a JSON body through theJsonextractor states its 400 and 422, plus its 415 when the body is required (json_body_routes_state_extractor_rejections; the daemon adds them to the document itself, and the routes that read their body by hand, listed inMANUAL_JSON_BODIESincrates/bookclerkd/src/openapi.rs, state their own refusals), and every example, on a field, a schema or a body, validates against the schema it illustrates, references followed and formats such asuuidanddate-timeasserted (every_example_matches_its_schema). The test build also compares every response the tests produce with the document and reports the disagreements in CI Gate (see Web API contract). A new field gets#[schema(example = …)]with a value the daemon really writes; a free-formserde_json::Valueor map field gets#[schema(schema_with = …)]returning a schema withexamples, since utoipa dropsexampleonvalue_type = Object; an error response a handler writes itself getsexample = json!(…)on its#[utoipa::path]entry.
Pull requests use a dependency-aware planner
(scripts/ci-plan.py), so only the affected
languages and packages run these checks. merge_group always runs the
full suite. Pushes to main only build and save caches, because the merge
group already tested the commit. See
Continuous integration.
The planner emits these generate-api-docs.sh selectors; the script
doesn't diff again itself:
./scripts/generate-api-docs.sh --check --all
./scripts/generate-api-docs.sh --check \
--rust-package bookclerk-config --typescript-sdk --ui --python
Follow the Google TypeScript style JSDoc conventions:
/**
* Fetches the guest's describe metadata over the host bridge.
*
* @param params - Bridge connection options.
* @returns Metadata including `apiVersion` and plugin kind.
* @throws {PluginError} When the host rejects the ABI version.
*
* @example
* ```ts
* const meta = await plugin.describe();
* ```
*/
export async function describe(params: DescribeOptions): Promise<PluginMetadata> {
The export surfaces for TypeDoc are packages/plugin-sdk (the npm
package) and ui/src (the operator SPA helpers). React components
document their props through the props type.
Use Google Python style docstrings:
def describe(self) -> PluginMetadata:
"""Fetch the guest's describe metadata over the host bridge.
Returns:
Metadata including ``api_version`` and plugin kind.
Raises:
PluginError: If the host rejects the ABI version.
"""
Every script starts with a header describing its purpose, usage and important environment variables (see the Google Shell style guide):
#!/usr/bin/env bash
#
# Generate language API references as HTML into target/api-docs/.
#
# Usage:
# ./scripts/generate-api-docs.sh [--check] [--all]
# ./scripts/generate-api-docs.sh --rust-package NAME --ui
#
# Environment:
# CARGO_TARGET_DIR - Optional Cargo target directory (default: target).
#
set -euo pipefail
- Writing docs: how to write the product docs pages.
- Plugin SDKs: the generated references, after each SDK's guide.
- Continuous integration: where these checks run.
Source: docs/contributing/code-documentation.md at main · View as Markdown