soothfast-docs API reference#

Generated by cargo soothfast docs reference Measurements and verified claims come from the latest baseline; CI gates them.

soothfast_docs#

soothfast_docs::claims#

Claim ^struct#

pub struct Claim

One parsed soothfast:claim expression: a measured metric of an item, compared against a fixed bound.

Op ^enum#

pub enum Op

Comparison operator of a claim expression (<, <=, >, >=).

evaluate ^function#

pub fn evaluate(claim: &Claim, baseline: &Value) -> Result<(bool, f64), String>

Evaluate against a baseline document; returns (holds, actual value).

parse ^function#

pub fn parse(expr: &str) -> Result<Claim, String>

Parse demo::lcg_checksum.perfcnt.instructions < 25000 (units on the bound: ns/us/ms/s multiply into ns; bare numbers stay raw).

soothfast_docs::diff#

SurfaceDiff ^struct#

pub struct SurfaceDiff

Public-API delta between two [Surface] snapshots, by item path.

compare ^function#

pub fn compare(old: &Surface, new: &Surface) -> SurfaceDiff

Diff two surfaces: added/removed items by path, changed items by span fingerprint (modules are exempt — their span is the whole file).

render ^function#

pub fn render(diff: &SurfaceDiff) -> String

One ADDED/REMOVED/CHANGED line per item, ready for terminals and changelog drafts; an empty diff renders as a single "no changes" line.

soothfast_docs::gentests#

GENERATED_HEADER ^constant#

pub const GENERATED_HEADER: &str = "// @generated by `cargo soothfast docs gen-tests`"

First line of every generated file; docs check uses it to tell generated artifacts from hand-written ones.

capture_examples ^function#

pub fn capture_examples(rel_path: &str, doc: &Doc) -> Vec<(String, String)>

Example-file contents for the capture blocks of one markdown doc, in capture order: (example_name, content).

A feature=NAME tag gates the real fn main behind that feature (feature=A,B behind all of them)

sanitized_stem ^function#

pub fn sanitized_stem(rel_path: &str) -> String

docs/measuring.md → soothfast_doc_docs_measuring.

test_file ^function#

pub fn test_file(rel_path: &str, doc: &Doc) -> Option<String>

Test-file content for one markdown doc, or None when it has no testable blocks (all ignored / non-rust / capture).

soothfast_docs::lockfile#

Binds ^type_alias#

pub type Binds = BTreeMap<String, String>

item path → fingerprint (hex).

LOCKFILE ^constant#

pub const LOCKFILE: &str = "soothfast.lock"

Lockfile name, resolved relative to the workspace root.

Lock ^struct#

pub struct Lock

Accepted binds, and the format version they were written under.

VERSION ^constant#

pub const VERSION: u64 = 2

Current lockfile format. Bumped whenever the fingerprint input changes, so a lock written by an older release reports as needing one re-accept rather than as prose that drifted.

comparable ^function#

pub fn comparable(lock: Lock) -> Result<Binds, String>

The entries of lock a fresh accept may merge over.

Fingerprints from an older format are not comparable to what this build derives, so they are dropped rather than carried under a stamp claiming they are current; their pages read as unlocked until their own docs accept runs, which is what lets a repo migrate one accept at a time.

A lock from a newer format is equally incomparable but is not this build's to discard, so it is refused instead. The asymmetry is the point: an older entry is worthless, a newer one is someone else's valid work. Accepting is deliberately stricter than checking here: a check against a newer lock only misreports, while an accept would overwrite it.

merge ^function#

pub fn merge(existing: &Binds, fresh: &Binds, full_scope: bool) -> Binds

Merge freshly accepted binds over existing. A full-scope accept replaces the map outright, dropping binds that no longer exist anywhere; a partial (explicit-paths) accept must preserve out-of-scope entries.

read ^function#

pub fn read(root: &Path) -> Result<Lock, String>

Read root's lockfile. A missing file is an empty map at the current version, not an error (a fresh repo has accepted nothing yet). A file without a version key predates the field and reads as v1.

write ^function#

pub fn write(root: &Path, binds: &Binds) -> Result<(), String>

Persist binds to root's lockfile as stable, pretty-printed JSON.

soothfast_docs::markdown#

Bind ^struct#

pub struct Bind

<!-- soothfast:bind path::to::item -->

ClaimMarker ^struct#

pub struct ClaimMarker

<!-- soothfast:claim item.backend.metric < value -->

CodeBlock ^struct#

pub struct CodeBlock

One fenced code block.

Doc ^struct#

pub struct Doc

Everything [scan] extracts from one markdown file: fenced code blocks plus soothfast:bind / soothfast:claim markers, in document order.

scan ^function#

pub fn scan(text: &str) -> Result<Doc, String>

Scan one markdown text. Closing markers (<!-- /soothfast:... -->) are structural for readers and ignored here. Errs on an unclosed fence: dropping it would silently swallow the block and every later marker.

splice_output ^function#

pub fn splice_output( text: &str, nth_capture: usize, output: &str, ) -> Result<Option<String>, String>

Replace (or insert) the text soothfast-output fence that follows the nth capture-output block (0-based among capture blocks). Ok(None) when the capture block wasn't found; Err on malformed markdown.

soothfast_docs::markdown::CodeBlock#

feature_list ^function#

pub fn feature_list(&self) -> Vec<&str>

Individual features of a feature= tag — one, or several comma-separated with no spaces (feature=risk,polygon; a space would split into a separate fence tag) when a block needs more than one feature to compile. Empty when the block has no feature= tag; scan rejects a tag whose value names no feature.

soothfast_docs::reference#

render ^function#

pub fn render( crate_name: &str, surface: &Surface, docs_text: &BTreeMap<String, String>, baseline: &Value, ) -> String

Render one crate's surface as a markdown fragment (module-grouped). baseline supplies measurements and assertion verdicts; pass Value::Null to render signatures + docs only.

resolve_reference_links ^function#

pub fn resolve_reference_links(text: &str) -> String

Rustdoc comments often disambiguate intra-doc links with a reference-style definition ([`Foo::bar`]: crate::Foo::bar); the site's markdown renderer only supports inline links. Drop each definition line and inline it into the shorthand [Foo::bar] references it defines. Doesn't handle the separate [text][label] reference form — not seen in practice here.

soothfast_docs::surface#

ItemGroup ^struct#

pub struct ItemGroup<'a>

One distinct item, grouped by (kind, fingerprint) to collapse the extra path keys alias_reexports adds for the same underlying function — representative is the shortest path (for display), aliases holds every spelling (for lookups, since a covers= tag may name any of them). Un-fingerprinted items (span unreadable) are never merged with others.

ItemInfo ^struct#

pub struct ItemInfo

What the surface records about one public item — enough to detect any change to it (fingerprint), classify the change (signature), and audit coverage (kind, has_docs).

Surface ^struct#

pub struct Surface

Public items keyed by full path (crate::module::item).

from_rustdoc ^function#

pub fn from_rustdoc(doc: &Value, source_root: &Path) -> Surface

Build a surface from a rustdoc JSON document. source_root resolves the relative filenames in spans (the directory rustdoc ran in).