Documentation
¶
Overview ¶
Package docx provides utilities for parsing and extracting metadata from Go source code comments.
Comment Structure ¶
A parsed comment block consists of three main parts:
Directives: Lines starting with `+genx:`. These are used to control the behavior of the generator. Format: `// +genx:name=parameter`
Annotations: Lines starting with `@`. These are used to attach arbitrary kv pairs or text to the element. Format: `// @name text` or `// @name key=value`
Description (Title + Tails): All other lines that are not directives, annotations, or prefixed with keywords (like TODO, BUG). The first line of the description is considered the "Title". The remaining lines are considered the "Tails" (or detailed description). Empty lines are skipped.
Index ¶
- type Annotation
- type Annotations
- type Directive
- type Directives
- type Meta
- func (m *Meta) Annotations() Annotations
- func (m *Meta) AnnotationsByName(name string) ([]Annotation, bool)
- func (m *Meta) Description(prefix string, sep string) string
- func (m *Meta) Descriptions(prefix string) []string
- func (m *Meta) Directive(name string) (Directive, bool)
- func (m *Meta) Directives() map[string]Directive
- func (m *Meta) Lines() []string
- func (m *Meta) Title(prefix string) string
Examples ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Annotation ¶
type Annotation struct {
// contains filtered or unexported fields
}
Annotation represents a parsed annotation (e.g., @name text).
func (*Annotation) Key ¶
func (a *Annotation) Key() string
Key returns the key part if the annotation text is in key=value format.
func (*Annotation) Name ¶
func (a *Annotation) Name() string
Name returns the name of the annotation.
func (*Annotation) Text ¶
func (a *Annotation) Text() string
Text returns the raw text following the annotation name.
func (*Annotation) Value ¶
func (a *Annotation) Value() string
Value returns the value part if the annotation text is in key=value format.
type Annotations ¶
type Annotations map[string][]Annotation
Annotations represents a collection of annotations grouped by name.
type Directive ¶
type Directive struct {
// contains filtered or unexported fields
}
Directive represents a parsed directive (e.g., +genx:name=parameter).
type Directives ¶
Directives represents a collection of directives keyed by name.
type Meta ¶
type Meta struct {
// contains filtered or unexported fields
}
Meta represents the parsed metadata from a comment block.
func Parse ¶
Parse parses a slice of comment lines into a Meta object. It extracts descriptions, annotations, and directives, while skipping lines that start with common keywords (like TODO, BUG, etc.).
Example ¶
m := docx.Parse([]string{
" Typename",
" Typename this line is title ",
" this is line 1 for descriptions ",
" this is line 2 for descriptions ",
" +genx:directive=directive parameters ... ",
" +genx:ignore=ignored1,ignored2,", // ignored directives
" +genx:ignored1", // redeclared directives
" + genx:... ", // invalid directive will be skipped
" +genx: ... ", // invalid directive will be skipped
" @attr k1=v1,attr parameters...",
" TODO prefixed with keywords ",
" todo keyword is case-sensitive",
" this is line 3 for descriptions ",
"", // empty line will be skipped
" @def annotation content ",
" @attr k2=v2,attr parameters...",
" @def ", // invalid annotation will be skipped
" @ def ", // invalid annotation will be skipped
})
fmt.Println("Description Lines")
for _, line := range m.Lines() {
fmt.Println(line)
}
fmt.Println()
fmt.Println("Description String")
fmt.Println(m.Description("Typename", "\n"))
fmt.Println()
fmt.Println("Description String No Prefix")
fmt.Println(m.Description("", "\n"))
fmt.Println()
fmt.Println("Annotations")
names := slices.Collect(maps.Keys(m.Annotations()))
slices.Sort(names)
for _, name := range names {
fmt.Printf("%s:\n", name)
annotations, _ := m.AnnotationsByName(name)
for _, anno := range annotations {
fmt.Printf("\tname: %s\n", anno.Name())
if k := anno.Key(); len(k) > 0 {
fmt.Printf("\tkey: %s\n", k)
}
if v := anno.Value(); len(v) > 0 {
fmt.Printf("\tvalue: %s\n", v)
}
fmt.Printf("\ttext: %s\n", anno.Text())
}
}
fmt.Println()
fmt.Println("Directives")
names = slices.Collect(maps.Keys(m.Directives()))
slices.Sort(names)
for _, key := range names {
d, _ := m.Directive(key)
fmt.Printf("%s:\n", key)
fmt.Printf("\tname: %s\n", d.Name())
if p := d.Parameter(); len(p) > 0 {
fmt.Printf("\tparameter: %s\n", p)
}
fmt.Printf("\tenabled: %t\n", d.Enabled())
}
fmt.Println()
fmt.Println("Empty documents")
fmt.Println("BEGIN")
fmt.Println(docx.Parse(nil).Description("", ""))
fmt.Println("END")
Output: Description Lines Typename Typename this line is title this is line 1 for descriptions this is line 2 for descriptions this is line 3 for descriptions Description String this line is title this is line 1 for descriptions this is line 2 for descriptions this is line 3 for descriptions Description String No Prefix Typename Typename this line is title this is line 1 for descriptions this is line 2 for descriptions this is line 3 for descriptions Annotations attr: name: attr key: k1 value: v1,attr parameters... text: k1=v1,attr parameters... name: attr key: k2 value: v2,attr parameters... text: k2=v2,attr parameters... def: name: def key: annotation content text: annotation content Directives directive: name: directive parameter: directive parameters ... enabled: true ignored1: name: ignored1 enabled: false ignored2: name: ignored2 enabled: false Empty documents BEGIN END
func (*Meta) Annotations ¶
func (m *Meta) Annotations() Annotations
Annotations returns all parsed annotations.
func (*Meta) AnnotationsByName ¶
func (m *Meta) AnnotationsByName(name string) ([]Annotation, bool)
AnnotationsByName returns annotations matching the given name.
func (*Meta) Description ¶
Description returns the description lines joined by the given separator. If prefix is provided, it trims the prefix from each line.
func (*Meta) Descriptions ¶
Descriptions returns the description lines.
func (*Meta) Directives ¶
Directives returns all parsed directives.
Source Files