Document Lifecycle and Side Effects
DOCS-DOCUMENT-LIFECYCLE-AND-SIDE-EFFECTS
Summary
Document caller-visible lifecycle, ownership, platform, feature, and side-effect obligations. Skip internal narration, but make operational responsibilities clear.
Rule
Document lifecycle, ownership, side effects, feature flags, platform assumptions, and compatibility when callers need them.
Why
APIs that open files, spawn tasks, touch terminals, allocate resources, mutate global state, enable feature flags, or depend on platform behavior create obligations for callers. If those obligations are not documented, examples can compile while still teaching unsafe cleanup, ownership, or compatibility assumptions.
Helps
- Makes caller obligations visible and reduces misuse around runtime, platform, feature, and cleanup behavior.
Limits
Do not narrate internal implementation. Document the lifecycle, side effects, and compatibility facts a caller must know to use or maintain the API correctly.
Agent Instruction
Document lifecycle, ownership, side effects, feature flags, platform assumptions, and compatibility
for APIs that create caller obligations.Mechanisms
Supported by Rustdoc contract sections, live-resource examples, feature tables, platform notes, doctests, and integration tests that exercise the documented lifecycle.