Code documentation (Google style)

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

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}/, outside docs/; CI doesn't keep it, so regenerate it locally.

Why

  • 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) and bookclerk-plugin-sdk (pdoc) mirror the same contract.
  • Contributors: public items can be found without reading call sites.

Universal rules

  1. 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 with RUSTFLAGS=-D warnings.
  2. Start with a one-sentence summary in the third person (not "This function…").
  3. Follow it with details, then the language's own sections for arguments, returns, errors or throws, and examples when useful.
  4. Prefer links to product docs (docs/plugins/README.md, ADRs) over repeating architecture essays in every item.
  5. Generated projections (SeaORM entities/* field mirrors, the ABI's generated.ts and abi.py synced from the schema) still get field-level summaries. Generators should emit or keep comments when they can.
  6. 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).

Quality bar (required)

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, # Returns and # Errors (or JSDoc @param, @returns, @throws, or Google Args, 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 # Examples or @example on entry-point APIs (PluginWorker, parse, serve, CLI helpers). CI compiles every rustdoc example (cargo test --doc). Crates without runnable examples report running 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).

Rust (rustdoc)

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 # Errors and # Panics Clippy denies cover private items there too.

Mechanical checks (CI)

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 --doc runs 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 the Test step (--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 copy crates/bookclerkd/openapi-3.0.json no longer matches the routes. Regenerate them with cargo run -p bookclerkd -- --print-openapi > crates/bookclerkd/openapi.json and cargo 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 and oneOf/allOf branches included, carries an example unless it is composed of other schemas or a one-value enum (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 the Json extractor 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 in MANUAL_JSON_BODIES in crates/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 as uuid and date-time asserted (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-form serde_json::Value or map field gets #[schema(schema_with = …)] returning a schema with examples, since utoipa drops example on value_type = Object; an error response a handler writes itself gets example = 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

TypeScript and JavaScript (JSDoc → TypeDoc)

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.

Python (Google docstrings → pdoc)

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.
    """

Shell (Google Shell style)

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

Next steps

Source: docs/contributing/code-documentation.md at main · View as Markdown