Skip to content
internal/ownership
Updated
On this page

Deciding whether a generated page's frontmatter description is a machine placeholder selfdoc may overwrite, or handwritten text it must never touch.

#internal/ownership

#internal/ownership

Package ownership decides whether a generated page's frontmatter description is machine-owned -- a placeholder selfdoc emitted and may freely overwrite -- or handwritten, and must never be overwritten.

The guiding principle: descriptions are handwritten; machine text is only ever a placeholder. The critical property is the INVERSE -- handwritten text must NEVER be classified machine-owned. The other direction is acceptable: legacy machine residue occasionally reads as handwritten when no seed hash was ever recorded for it, and the next gen reseeds it, since a release always runs gen before check.

Ownership is decided per page kind:

- module pages: the current or the historical instantiated template for that module, or the recorded seed hash. - the generated API index: the current or a legacy index template, or the recorded seed hash. - CLI pages: a live recompute from the dumped schema (which covers the truncated-prefix family no static set can), or the recorded seed hash.

The seed hash is the SHA-256 of the machine-emitted description TEXT, recorded per page by gen in the staleness store. An unrecorded seed hash is the empty string.

#ModuleDescTemplate

Go go
const ModuleDescTemplate = "API reference for the {module} module — " +

ModuleDescTemplate is the current auto-generated description of a module reference page, with "{module}" standing for the module's name.

The predicate compares a description against this text for equality, so every character of it -- the em dash included -- is part of the contract: a changed byte turns every page carrying the old text into handwritten prose that gen may no longer reseed.

#HistoricalModuleDescTemplate

Go go
const HistoricalModuleDescTemplate = "Documentation for {module}"

HistoricalModuleDescTemplate is the module page description a pre-current-template selfdoc emitted. It is still recognized, so that residue is reseeded rather than frozen as if a person had written it.

#LegacyIndexDescriptions

Go go
var LegacyIndexDescriptions = []string{

LegacyIndexDescriptions are the machine-seeded generated-index descriptions produced by selfdoc versions that recorded no seed hash.

They hardcode "selfdoc" and so are wrong for every consuming project; they are treated as machine residue and reseeded.

#NormalizeDescription

Go go
func NormalizeDescription(value any) string

NormalizeDescription strips surrounding whitespace and one layer of matching quotes, so a description written as 'x' or "x" in frontmatter compares equal to the same text written bare.

#DescriptionSeedHash

Go go
func DescriptionSeedHash(value any) string

DescriptionSeedHash is the SHA-256 of a normalized machine-emitted description string. It is what gen records per page, and what the predicates below compare a page's current text against.

#IsMachineOwnedModuleDescription

Go go
func IsMachineOwnedModuleDescription(value any, moduleName, seedHash string) bool

IsMachineOwnedModuleDescription reports whether value is machine-owned for a module page documenting moduleName.

An empty moduleName means the page carries no title to instantiate the templates with, so only the recorded seed hash can answer.

#IsMachineOwnedIndexDescription

Go go
func IsMachineOwnedIndexDescription(value any, seedHash string) bool

IsMachineOwnedIndexDescription reports whether value is a machine-owned description of the generated API index page.

#IsMachineOwnedCLIDescription

Go go
func IsMachineOwnedCLIDescription(

IsMachineOwnedCLIDescription reports whether value is a machine-owned description of a CLI page.

CLI machine text is derivable from the dumped schema, so beyond the recorded seed hash this is a live recompute: no static set can cover the family of truncated defaults earlier selfdoc versions wrote.

#IsMachineOwned

Go go
func IsMachineOwned(

IsMachineOwned classifies a page's description as machine-owned (true) or handwritten (false).

relPath selects the page kind by its filename; frontmatter supplies the description, and the title for a module page. seedHash is the page's recorded seed hash from the staleness store, "" when none was recorded. cliStructure is the parsed dumped schema, needed to look up a CLI command's help text; pass nil for a project that is not strictcli-based.

Handwritten text is never classified machine-owned. Only a page declaring generated: true can be machine-owned at all, so a hand-authored page always answers false and keeps its full staleness protection.

Search