doc

type ChildHeading struct {
	Level       int
	Text        string
	Line        int // 1-based line number of the heading in source
	StartOffset int // byte offset of the heading's first byte in source
}

type DocAttribute struct {
	Name        string
	Required    bool
	Optional    bool
	ReadOnly    bool
	Deprecated  bool
	Description string
	Line        int // 1-based line number in the source file
}

type DocBlock struct {
	Name                string
	Heading             string
	Attributes          []DocAttribute
	MalformedAttributes []MalformedAttr // attributes found but with formatting issues
	SplitByLabel        bool            // true if the doc explicitly separates required/optional with distinct bylines
}

type Document struct {
	ResourceName    string
	ArgumentBlocks  map[string]*DocBlock
	AttributeBlocks map[string]*DocBlock
	Sections        *Sections
	// contains filtered or unexported fields
}

type HeadingTemplates []string

type MalformedAttr struct {
	Name string
	Line int
}

type NestedRef struct {
	Parent      string // dot-separated path with array indexers stripped
	Attribute   string // leaf attribute name
	Description string
	Required    bool
	Optional    bool
	ReadOnly    bool
}

type Section struct {
	Heading          *ast.Heading
	Text             string
	FencedCodeBlocks []*ast.FencedCodeBlock
	Paragraphs       []*ast.Paragraph

	// ChildHeadings are headings at level > the section's own level that
	// appear before the next same-or-lower-level heading. Used by rules
	// that check for required sub-sections (e.g. "### Basic Usage" inside
	// "## Example Usage").
	ChildHeadings []ChildHeading

	// ListItems are the top-level list items found in this section. Used by
	// rules that validate structured lists (e.g. timeout actions).
	ListItems []SectionListItem

	// StartOffset and EndOffset are byte offsets into the source marking the
	// section's extent (from the heading's first byte to the byte before the
	// next same-or-lower-level heading, or EOF). Rules that need raw source
	// patterns (e.g. import block format) slice source[StartOffset:EndOffset].
	StartOffset int
	EndOffset   int
}

type SectionListItem struct {
	Name  string
	Value string
	Line  int
}

type Sections struct {
	Title      *Section // level-1 heading (# Resource: foo)
	Signature  *Section // ## Signature (functions)
	Example    *Section // ## Example Usage
	Arguments  *Section // ## Argument Reference
	Attributes *Section // ## Attribute Reference
	Timeouts   *Section // ## Timeouts
	Import     *Section // ## Import

	// UnknownHeadings records every level-2 heading that did not map to one
	// of the recognized sections above. The parser captures these so the
	// section_presence rule can flag stray sections like ## My wild heading.
	// Each entry's Level is always 2; Text is the raw heading text.
	UnknownHeadings []ChildHeading
}