Module stdlib_metadata 

Structured metadata declared in stdlib HarnDoc blocks.

Public stdlib functions carry a prose summary plus two required machine-meaningful fields above their pub fn declaration:

/**
 * Returns the contents of `path`.
 *
 * @effects: [fs.read]
 * @errors: [FileNotFound, PermissionDenied]
 */
pub fn read_to_string(...) -> ... { ... }

Two more fields are optional:

• @api_stability: — stability promise (experimental, internal, …). Absent means stable.
• @example: — a hand-written usage example, only worth writing when it shows something the signature cannot. When absent, tooling synthesizes one from the type signature (synthesize_example).

These fields drive harn graph --json, LSP hover, and the HARN-STD-101 lint that enforces coverage on stdlib sources.

Structs

StdlibMetadata

One declared metadata field on a stdlib function. Empty lists and missing fields are distinct: effects: Some(vec![]) records an explicit [] declaration (“statically certified pure”), while effects: None means the author has not annotated the function yet.

Functions

parse_for_span

Extract a canonical /** ... */ block immediately above the given span and parse its metadata fields. Returns the parsed metadata even if no fields are declared so callers can detect “doc present, fields missing”.

parse_from_doc_body

Parse all @key: value fields from the body of a canonical /** ... */ HarnDoc block. The body should be the inner text with /**, leading *, and */ markers already stripped, one line per element. Multi-line @example: continuations are joined while preserving trailing newlines.

synthesize_example

Synthesize a usage example from a function signature, for symbols whose docs carry no hand-written @example. LSP hover and harn graph --json present the result labeled as derived.