Skip to content

index.md

Latest commit

 

History

History
189 lines (140 loc) · 4.8 KB

index.md

File metadata and controls

189 lines (140 loc) · 4.8 KB

Std API Documentation

This page defines how AICore standard-library API documentation is generated and maintained.

Source of truth

  • std/*.aic (including std/bytes.aic): canonical API declarations.
  • src/std_policy.rs: snapshot collector and compatibility comparator.
  • docs/std-api-baseline.json: machine-readable baseline consumed by aic std-compat.

Generation workflow

  1. Update std modules under std/.
  2. Regenerate snapshot:
cargo run --quiet --bin aic -- std-compat > docs/std-api-baseline.json
  1. Validate compatibility against baseline:
cargo run --quiet --bin aic -- std-compat --check --baseline docs/std-api-baseline.json
  1. If --check reports E6002, either:
  • restore backward compatibility, or
  • explicitly document a migration and intentionally update baseline in the same change.

The check treats removed/changed symbols as breaking and additive symbols as compatible.

Std doc coverage gate

make std-doc-check enforces /// documentation in std/*.aic for:

  • module headers (module ...;)
  • struct, enum, and trait declarations
  • enum variants
  • fn and intrinsic fn declarations (including methods inside impl)

Autofix helper:

python3 scripts/ci/std_doc_coverage.py --fix

aic doc generation contract

aic doc <input> --output <dir> creates <dir> when missing. With the default --format all, it emits:

  • index.html: human-readable browsable API reference with client-side search.
  • index.md: human-readable markdown API reference suitable for repository docs.
  • api.json: machine-readable module/item payload (schema_version = 1).

Use these commands to validate module and std documentation generation behavior:

aic doc examples/e4/verified_abs.aic --output target/docs-contract/module-docs aic doc std/fs.aic --output target/docs-contract/std-fs-docs

Each command above must produce the following files inside its output directory:

index.html index.md api.json

Module coverage

Current baseline snapshot (schema_version: 1) covers these modules:

Module
std.buffer
std.bytes
std.char
std.concurrent
std.config
std.crypto
std.deque
std.env
std.error_context
std.fs
std.http
std.http_server
std.io
std.iterator
std.json
std.map
std.math
std.net
std.numeric
std.option
std.path
std.pool
std.proc
std.rand
std.regex
std.result
std.retry
std.router
std.secure_errors
std.string
std.set
std.signal
std.tls
std.time
std.url
std.vec

For exact symbol totals and kind distribution, query the baseline directly:

jq -r '.symbols | length' docs/std-api-baseline.json
jq -r '.symbols | group_by(.kind)[] | "\(.[0].kind): \(length)"' docs/std-api-baseline.json

Signature policy

Documented signatures must match snapshot rendering rules from src/std_policy.rs:

  • Functions: name[generics](params) -> Ret effects { ... }
  • Structs: Name[generics] { field: Type, ... }
  • Enums: Name[generics] { Variant, Variant(Type), ... }
  • Traits: TraitName[generics];
  • Impls: TraitName[TypeArgs];

Rules:

  • Keep parameter names and effect sets exactly as declared in std modules.
  • Keep generic bounds in signatures when present.
  • Do not normalize or alias module names in rendered signatures.

Effects policy

Effects recorded in the std baseline currently include:

  • concurrency
  • env
  • fs
  • io
  • net
  • proc
  • rand
  • time

For each effectful API in docs:

  • include the exact effects { ... } list,
  • document required effect declarations at call sites,
  • call out effect/capability diagnostics where relevant (E2001-E2009).

Errors policy

For APIs returning Result[T, E]:

  • document the error enum (E) and expected failure classes,
  • separate deterministic validation failures from environment/runtime failures,
  • include diagnostics users will most often see when misuse occurs (for example E2001, E212x, E50xx, E6001, E6002).

Examples policy

Examples must stay concise and compile-intent aligned with AIC syntax.

Required structure for each std API page section:

  1. one minimal success-path snippet,
  2. one failure-path snippet (or usage note) that demonstrates error/effect constraints,
  3. clear module-qualified names when ambiguity is possible.

Example style:

module demo.main;

fn main() -> Result[String, FsError] effects { fs } capabilities { fs } {
  std.fs.read_text("README.md")
}

Related docs

  • docs/data-bytes.md
  • docs/std-api/tls.md
  • docs/std-api/machine-readable.md
  • docs/std-compatibility.md
  • docs/io-api-reference.md