Documentation
¶
Overview ¶
Package docstd is the canonical vocabulary for the boxer documentation standard's front-matter contract (DOCUMENTATION_STANDARD §4): the allowed Diátaxis `type:` values, the per-type `status:` lifecycle enums, and a pure validator over a `(type, status)` pair.
It is the single source of truth shared by the two enforcers of that contract:
- github.com/stergiotis/boxer/public/gov/doclint — the repo-wide CI linter (rule DL001) walking every Markdown file under doc-standard scope.
- github.com/stergiotis/boxer/public/keelson/runtime/help — the runtime help library validating each app's embedded help corpus.
The two differ in exactly one axis, captured by the allowADR parameter of ValidateFrontmatter: repo-wide linting accepts `type: adr`, while operator-facing inline help does not (an ADR is design history, not help). Everything else — the type spellings, the descriptive vs ADR status sets, the missing-field precedence — is identical, so it lives here once.
The package is intentionally a pure leaf: it imports only the standard library, takes already-extracted strings rather than raw bytes, and knows nothing about file paths, line numbers, or severity policy. Each consumer maps the returned Violation values onto its own finding type with its own positioning and severity. Front-matter extraction and YAML parsing stay with the consumer.
Index ¶
Constants ¶
const ( TypeReference = "reference" TypeHowTo = "how-to" TypeExplanation = "explanation" TypeTutorial = "tutorial" TypeADR = "adr" )
Diátaxis document types — the canonical `type:` front-matter values from DOCUMENTATION_STANDARD §4. The first four are the reader-facing content quadrants; TypeADR is design history, accepted repo-wide but not in operator-facing help corpora.
const ( StatusDraft = "draft" StatusStable = "stable" StatusDeprecated = "deprecated" StatusSuperseded = "superseded" )
Descriptive-doc lifecycle statuses (README / EXPLANATION / HOWTO / TUTORIAL). ADRs use the StatusProposed set instead; StatusDeprecated and StatusSuperseded are shared by both.
const ( StatusProposed = "proposed" StatusAccepted = "accepted" StatusDeferred = "deferred" StatusWithdrawn = "withdrawn" )
ADR-only lifecycle statuses. StatusDeprecated and StatusSuperseded from the descriptive set are also valid for ADRs. StatusWithdrawn records a proposal retracted before it was ever accepted or implemented — distinct from deprecated, which implies prior adoption; the ADR is kept under the append-only convention as a record of the rejected option.
Variables ¶
var PackageProps = packageprops.Props{ WASMWASI: packageprops.WASMCompiles, WASMJS: packageprops.WASMCompiles, WASMFreestanding: packageprops.WASMCompiles, }
PackageProps records this package's curated properties (ADR-0080). Seeded by `boxer code analysis golang wasmsurvey props generate`; curate by hand. The same group's `props verify` reconciles it.
Functions ¶
func IsContentType ¶
IsContentType reports whether t is a Diátaxis content type — one of the reader-facing quadrants (reference, how-to, explanation, tutorial), excluding adr. Inline help corpora are restricted to these.
func IsStatusForType ¶
IsStatusForType reports whether status is a valid lifecycle state for a doc of the given type. ADRs (TypeADR) use the proposed/accepted/ deferred/withdrawn set (plus the shared deprecated/superseded); every other type (including an empty or unknown one) uses the descriptive set, matching the standard's required-field precedence.
Types ¶
type Violation ¶
type Violation struct {
// Field is the offending front-matter key: "type" or "status".
Field string
// Value is the offending value, or "" when the field is absent.
Value string
// Message is a self-contained, human-readable description of the
// breach, suitable for display after a "<file>: " prefix.
Message string
}
Violation is one front-matter contract breach for a (type, status) pair, free of consumer-specific concerns like file path, line number, or severity. The two enforcers (github.com/stergiotis/boxer/public/gov/doclint and the keelson help library) map it onto their own finding type.
func ValidateFrontmatter ¶
ValidateFrontmatter checks a document's `type` and `status` front-matter values against DOCUMENTATION_STANDARD §4 and returns one Violation per breach. An empty result means the pair is conformant.
allowADR selects the accepted type set: repository-wide doc linting passes true (adr is a valid type); operator-facing inline help passes false, since an ADR is design history, not help. The status enum is keyed on the document's type via IsStatusForType.
Violations are returned in field order (type, then status). A missing `status` short-circuits the status-enum check — the only thing to say about an absent value is that it is required.
Source Files