Documentation
¶
Overview ¶
Package apiref generates the SDK API reference, docs/reference/api/, from the Go sources of every published module: for each non-internal package its import path, its synopsis and its stability label, then every exported constant, variable, function and type (with the constructors and methods go/doc groups under it) as the declaration and the first sentence of its doc comment. It uses only the standard library (go/parser, go/doc, go/printer), so it adds no dependency, and the output is a pure function of the sources: sorted, with no timestamps.
The pages are checked by TestAPIReference, which fails when they differ from the sources; regenerate with go test ./internal/tools/apiref -run TestAPIReference -update.
Which packages are listed: every package of every module in the repository except the modules that are never published (the REPO_ONLY and COMMANDS lists of scripts/release.sh), directories named internal, testdata, examples, assets or cmd, and package main. Files are selected for linux/amd64 with cgo enabled, so a symbol that exists only on another platform is not listed.
Index ¶
Constants ¶
const ( Core = "core" Experimental = "experimental" BuildingBlock = "building block, not yet used by approval gates" )
The stability labels. Their meaning is stated in docs/trust/stability.md.
const PageDir = "docs/reference/api"
PageDir is the directory of the generated pages, relative to the repository root.
Variables ¶
var Default = Config{Labels: Labels, Rules: SymbolRules}
Default is the repository's own configuration.
var Labels = map[string]string{ "agent": Core, "agent/agenttest": Core, "agent/storetest": Core, "anchor/awss3": Experimental, "anchor/awss3/awss3test": Experimental, "anchor/gcs": Experimental, "anchor/gcs/gcstest": Experimental, "approvals": Core, "audit": Core, "audit/anchorobj": Experimental, "audit/crlrefresh": Experimental, "audit/eventstoretest": Core, "audit/rfc3161": BuildingBlock, "audit/verify": Core, "chaos": Experimental, "codec/gcf": Core, "eval": Experimental, "flowedit": Experimental, "govern": Experimental, "govern/eventlogtest": Experimental, "govern/postgreslog": Experimental, "govern/redislog": Experimental, "govern/sqlitelog": Experimental, "mcptools": Core, "middleware": Core, "model/anthropic": Core, "model/gemini": Core, "model/modeltest": Core, "model/openai": Core, "model/provider": Core, "notify": Core, "notify/relay": Experimental, "plan": Experimental, "plan/planview": Experimental, "schema": Core, "signer/awskms": Core, "signer/azurekv": Core, "signer/gcpkms": Core, "signer/pkcs11": Core, "signer/pkcs11/pkcs11test": Core, "store/postgres": Core, "store/sqlite": Core, "theme": Experimental, "trace": Core, }
Labels is the single declared source of the package stability labels, keyed by import path relative to the path of the repository's root module (github.com/bide-ai/bide). Render fails when a documented package has no label, TestPackageLabels fails when a label names no package, and TestStabilityPage fails when the table in docs/trust/stability.md differs from this one.
var SymbolRules = []SymbolRule{ { Package: "agent", Files: []string{"hold.go", "notify_stop.go", "redact_run.go", "taint_marks.go", "stop_control.go", "stop_hold.go", "stop_policy.go", "stop_record.go", "stop_switch.go", "stop_trail.go"}, Names: []string{"WithRecoverStop", "RunEnded", "Redactor", "Compactor", "CompactionReport", "RedactState", "ErrRedactNotTerminal", "ErrRedactLeased", "ErrRedactProtected", "ErrRedactMismatch", "ErrRedactSession", "ErrRedactParentLive", "ErrRedactChanged", "ErrRedactNoEntry", "RedactionProtected", "RedactionEndMarkers", "CheckRedaction", "RedactionAncestors", "RedactionSession"}, Label: Experimental, }, { Package: "audit", Files: []string{"hold_authorization.go", "redaction_trail.go", "stop_trail.go", "stop_verify.go"}, Names: []string{"ErrRedacted", "NoteRedacted"}, Label: Experimental, }, }
SymbolRules label the parts of a package that are further along, or less far along, than the package. The kill switch, accountable erasure (redaction), legal holds and the untrusted-content declarations (taint_marks.go) are experimental inside the core packages: their API may change in a minor release while the audit guarantees they state hold (docs/trust/stability.md).
Functions ¶
func Render ¶
Render returns the pages, keyed by file name under PageDir: index.md and one page per module. It assigns each package its label and fails when a package has none.
func Undocumented ¶
Undocumented lists the exported symbols of the packages that have no doc comment, as "import/path Name". doccheck enforces the same rule on every module; this keeps the page from ever listing a symbol with nothing to say.
Types ¶
type Config ¶
type Config struct {
Labels map[string]string
Rules []SymbolRule
}
A Config is the label tables a page is rendered with.
type Entry ¶
type Entry struct {
Name string // "Name", or "Type.Method" for a method
Decl string
Sentence string
File string // base name of the file that declares it
}
An Entry is one function, method or type: its declaration and the first sentence of its doc.
type Item ¶
type Item struct {
Name string
Spec string // "const Name Type = value", the value elided when long or implicit
Sentence string
File string
}
An Item is one exported name of a Value. Its sentence is its own doc comment, or the group's.
type Module ¶
type Module struct {
Path string // module path
Dir string // slash-separated directory relative to the repository root; "." for the core
Packages []*Package
}
A Module is one published Go module and its packages.
type Package ¶
type Package struct {
ImportPath string
Rel string // ImportPath relative to the root module's path: the key of the label tables
Name string
Synopsis string
Label string // the stability label of the package
Consts []Value
Vars []Value
Funcs []Entry
Types []Type
// contains filtered or unexported fields
}
A Package is one documented package.
type SymbolRule ¶
type SymbolRule struct {
Package string // import path relative to the core module
Files []string
Names []string
Label string
}
A SymbolRule labels symbols of a package whose label is a different one: the symbols declared in Files, and the symbols called Names (or the methods of a type so called).
Source Files