Spanda

Spanda Coding Standards — Documentation

Repository-wide docstring standard for every method, function, trait method, implementation method, public API, CLI handler, provider method, verifier method, runtime method, and package API.

Scope: documentation only — no behavior, logic, or signature changes.

Placement

Structured documentation must appear in one of these locations (not both with duplicated content):

  1. Inside the function body (Spanda repo default) — first lines of the body, using // line comments (Rust/TypeScript) or a docstring (Python).
  2. Immediately above the signature — Rust /// doc comments or TypeScript /** … */ JSDoc, for items that must appear in rustdoc / generated API reference.

Avoid excessive duplication between outer /////** blocks and inner body headers.

Required sections

Every documented callable must include:

Section Purpose
Description Why the callable exists — not a restatement of its name
Inputs Each parameter: name, type, purpose
Outputs Return value: name, type, meaning
Example Realistic usage snippet (should compile where practical)

Optional sections

Format

Rust (inline body — default)

pub fn validate(proposal: ActionProposal) -> Result<SafeAction, SafetyError> {
    // Description:
    //     Validates a proposed autonomous action and converts it into a SafeAction
    //     when all safety constraints pass.
    //
    // Inputs:
    //     proposal: ActionProposal
    //         Proposed action generated by planner or agent.
    //
    // Outputs:
    //     action: Result<SafeAction, SafetyError>
    //         Verified action approved for execution, or a safety violation error.
    //
    // Example:
    //     let proposal = planner.reason(goal);
    //     let action = safety.validate(proposal)?;

    // Evaluate geofence and speed caps before approving motion.
    …
}

Rust (/// — public rustdoc)

/// Description:
///     Validates a proposed autonomous action and converts it into a SafeAction
///     when all safety constraints pass.
///
/// Inputs:
///     proposal: ActionProposal
///         Proposed action generated by planner or agent.
///
/// Outputs:
///     action: Result<SafeAction, SafetyError>
///         Verified action approved for execution.
///
/// Example:
///     let proposal = planner.reason(goal);
///     let action = safety.validate(proposal)?;
pub fn validate(proposal: ActionProposal) -> Result<SafeAction, SafetyError> {
    …
}

Spanda language (.sd)

/// Description:
///     Plans a path between two poses.
///
/// Inputs:
///     start: Pose
///         Starting position.
///
///     goal: Pose
///         Destination position.
///
/// Outputs:
///     path: Path
///         Generated navigation path.
///
/// Example:
///     let route = plan_path(current_pose, target_pose);
fn plan_path(start: Pose, goal: Pose) -> Path {
    …
}

TypeScript (inline body — default)

export function remoteFetch(url: string, init: RequestInit = {}): Promise<Response> {
  // Description:
  //     Issues one HTTP request with a bounded total lifetime and abort propagation.
  //
  // Inputs:
  //     url: string
  //         Request URL.
  //
  //     init: RequestInit
  //         Standard fetch options; optional upstream abort signal.
  //
  // Outputs:
  //     response: Promise<Response>
  //         Fetch response when the request completes.
  //
  // Example:
  //     const res = await remoteFetch("https://api.example.com/health");

  …
}

TypeScript (JSDoc — when exported to API docs)

JSDoc may use @param, @returns, and @example instead of Inputs / Outputs / Example headings; the validator maps these equivalently.

Python

def add_binary(a, b):
    """
    Description:
        Return the sum of two decimal numbers as binary digits.

    Inputs:
        a: int
            A decimal integer.
        b: int
            Another decimal integer.

    Outputs:
        binary_sum: str
            Binary string of the sum of a and b.

    Example:
        add_binary(5, 7)  # => "1100"
    """
    …

Quality rules

Descriptions

Explain why the API exists.

Bad Good
Gets health. Retrieves the current evaluated health status for a robot, including health score and issues.

Inputs

Every parameter needs name, type, and purpose:

Inputs:
    rover_id: String
        Unique identifier of the robot being evaluated.

Outputs

Every return value needs name, type, and meaning:

Outputs:
    report: ReadinessReport
        Readiness evaluation result.

Use Outputs: None. for () / void returns.

Examples

Public APIs must include a realistic Example section. Prefer snippets that compile in context.

Module documentation

Coverage areas

Apply this standard across:

Tooling

Script Purpose
scripts/validate_documentation.py Audit coverage; emit warnings for gaps
scripts/validate_documentation.py --report Regenerate docs/documentation-coverage.md
scripts/add_structured_api_docs.py Bulk-add missing structured docs (body placement)
scripts/repair_doc_param_typos.py Fix truncated names in generated docs
scripts/fix_structured_doc_gaps.py Fix empty Inputs and legacy single-line comments
scripts/normalize_inline_docs.py Fix spacing and block-comment indentation

CI enforcement

CI runs python3 scripts/validate_documentation.py --warn --report in CI Integration docs-build (and CI Fast docs-validate for docs-only PRs). Missing structured documentation emits warnings only; builds do not fail yet.

Legacy format

Older blocks using Parameters, Returns, and Options are accepted during transition but should be migrated to Description / Inputs / Outputs / Example. Run:

python3 scripts/migrate_legacy_inline_docs.py
python3 scripts/add_structured_api_docs.py
python3 scripts/fix_structured_doc_gaps.py
python3 scripts/repair_doc_param_typos.py
python3 scripts/normalize_inline_docs.py
This site is open source. Improve this page.