# API Docs Lint

> API Docstring Style Guide

- Skill: `oxidecomputer/api-docs-lint` (Agent Skill)
- Install (CLI): `npx skillmds@latest add oxidecomputer/api-docs-lint`
- Raw SKILL.md: https://api.skillmd.com/api/skills/oxidecomputer/api-docs-lint/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: oxidecomputer (https://skillmd.com/u/oxidecomputer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/oxidecomputer/api-docs-lint

---

# API Docstring Style Guide

This guide covers public docstrings (`///`) on endpoint handlers in
`nexus/external-api/src/lib.rs` and on structs, fields, and enums in
`nexus/types/src/external_api/`. These docstrings become user-facing API
documentation.

## Capitalization

Start all docstrings with a capital letter.

```rust
// Bad
/// the source of an identity provider metadata descriptor
pub idp_metadata_source: IdpMetadataSource,

// Good
/// The source of an identity provider metadata descriptor.
pub idp_metadata_source: IdpMetadataSource,
```

## Punctuation

Short, label-like descriptions do not need periods. This includes endpoint
summary lines, struct-level descriptions, and brief field annotations. Longer
explanatory text (especially multi-clause or multi-sentence docstrings) should
end sentences with periods.

```rust
// Endpoint summary lines: no period
/// Fetch silo
/// List identity providers for silo
/// Create IP pool

// Struct-level descriptions: no period
/// View of a Silo
/// A collection of resource counts used to describe capacity and utilization

// Short field descriptions: no period
/// Number of virtual CPUs
/// Common identifying metadata
/// Size of blocks in bytes

// Longer explanatory text: use periods
/// Accounts for resources allocated to running instances or storage
/// allocated via disks or snapshots.
///
/// Note that CPU and memory resources associated with stopped instances
/// are not counted here, whereas associated disks will still be counted.
```

## Articles

Omit articles ("a", "an", "the") in endpoint summary lines. Look at existing
endpoints in `nexus/external-api/src/lib.rs` for reference. A few examples of
the different shapes:

```rust
// Bad
/// Fetch a silo
/// Create an IP pool
/// Delete the project
/// List the silos

// Good
/// Fetch silo
/// Create IP pool
/// Delete project
/// List silos
/// Fetch resource utilization for user's current silo
/// List identity providers for silo
/// Add range to IP pool
```

## Paragraph Separation

Separate distinct thoughts or notes with a blank `///` line. This produces
proper paragraph breaks in rendered documentation.

```rust
// Bad - renders as one run-on paragraph
/// A unique, immutable, system-controlled identifier for the token.
/// Note that this ID is not the bearer token itself, which starts with
/// "oxide-token-".
pub id: Uuid,

// Good - renders as two paragraphs
/// A unique, immutable, system-controlled identifier for the token.
///
/// Note that this ID is not the bearer token itself, which starts with
/// "oxide-token-".
pub id: Uuid,
```

## Acronyms and Abbreviations

Use standard casing for acronyms:
  - "IdP" (Identity Provider)
  - "SP" (Service Provider)
  - "SAML", "ID", "IP", "VPC", "CPU", "RAM", "DER"

## Doc Comments vs Regular Comments

Use `///` for public API documentation that users will see. Use `//` for
internal implementation notes that should not appear in generated docs.

```rust
// Bad - this won't appear in API docs
// A list containing the IDs of the secret keys.
pub secrets: Vec<WebhookSecret>,

// Good - this will appear in API docs
/// A list containing the IDs of the secret keys.
pub secrets: Vec<WebhookSecret>,
```

## Scope

These rules apply to:
- Endpoint handler docstrings (`/// Fetch silo`)
- Public struct docstrings (`/// View of a Silo`)
- Public field docstrings (`/// The IP address held by this resource.`)
- Public enum variant docstrings (`/// The sled is currently active.`)

These rules do NOT apply to:
- Private functions or structs
- Internal comments (`//`)
- Module-level documentation (`//!`)

## General

Follow standard English grammatical rules: correct articles ("a" vs "an"),
subject-verb agreement, proper spelling, etc.