Skip to content

Commit

Permalink
Move walk over docs to a separate type, add docstings (#218)
Browse files Browse the repository at this point in the history 
* upgrade dependencies
* move docs walk to a separate type
* fix linter warnings, add docstings
  • Loading branch information
@mlange-42
mlange-42 authored Feb 9, 2025
1 parent 06723d7 commit 8b2bd88
Show file tree
Hide file tree
Showing 16 changed files with 189 additions and 134 deletions.
2 changes: 1 addition & 1 deletion go.mod
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ require (
github.com/pkg/profile v1.7.0
github.com/rjeczalik/notify v0.9.3
github.com/spf13/cobra v1.8.1
github.com/spf13/pflag v1.0.5
github.com/spf13/pflag v1.0.6
github.com/spf13/viper v1.19.0
github.com/stretchr/testify v1.10.0
gopkg.in/ini.v1 v1.67.0
Expand Down
3 changes: 2 additions & 1 deletion go.sum
View file
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,9 @@ github.com/spf13/cast v1.6.0 h1:GEiTHELF+vaR5dhz3VqZfFSzZjYbgeKDpBxQVS4GYJ0=
github.com/spf13/cast v1.6.0/go.mod h1:ancEpBxwJDODSW/UG4rDrAqiKolqNNh2DX3mk86cAdo=
github.com/spf13/cobra v1.8.1 h1:e5/vxKd/rZsfSJMUX1agtjeTDf+qv1/JdBF8gg5k9ZM=
github.com/spf13/cobra v1.8.1/go.mod h1:wHxEcudfqmLYa8iTfL+OuZPbBZkmvliBWKIezN3kD9Y=
github.com/spf13/pflag v1.0.5 h1:iy+VFUOCP1a+8yFto/drg2CJ5u0yRoB7fZw3DKv/JXA=
github.com/spf13/pflag v1.0.5/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/pflag v1.0.6 h1:jFzHGLGAlb3ruxLB8MhbI6A8+AQX/2eW4qeyNZXNp2o=
github.com/spf13/pflag v1.0.6/go.mod h1:McXfInJRrz4CZXVZOBLb0bTZqETkiAhM9Iw0y3An2Bg=
github.com/spf13/viper v1.19.0 h1:RWq5SEjt8o25SROyN3z2OrDB9l7RPd3lwTWU8EcEdcI=
github.com/spf13/viper v1.19.0/go.mod h1:GQUN9bilAbhU/jgc1bKs99f/suXKeUMct8Adx5+Ntkg=
github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
Expand Down
4 changes: 2 additions & 2 deletions internal/cmd/util.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -73,10 +73,10 @@ func readDocs(file string) (*document.Docs, error) {
}

if strings.HasSuffix(file, ".yaml") || strings.HasSuffix(file, ".yml") {
return document.FromYaml(data)
return document.FromYAML(data)
}

return document.FromJson(data)
return document.FromJSON(data)
}

func read(file string) ([]byte, error) {
Expand Down
3 changes: 3 additions & 0 deletions internal/document/config.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,6 +8,7 @@ import (
"github.com/spf13/viper"
)

// Config holds the configuration for the documentation processor.
type Config struct {
InputFiles []string `mapstructure:"input" yaml:"input"`
Sources []string `mapstructure:"source" yaml:"source"`
Expand All @@ -31,6 +32,7 @@ type Config struct {
PostRun []string `mapstructure:"post-run" yaml:"post-run"`
}

// ConfigFromViper creates a new Config from a viper.Viper instance.
func ConfigFromViper(v *viper.Viper) (*Config, error) {
c := Config{}
if err := v.Unmarshal(&c); err != nil {
Expand Down Expand Up @@ -63,6 +65,7 @@ func (c *Config) check(v *viper.Viper) error {
return nil
}

// RemovePostScripts removes all post-run, post-build, and post-test scripts.
func (c *Config) RemovePostScripts() {
c.PostTest = nil
c.PostBuild = nil
Expand Down
12 changes: 7 additions & 5 deletions internal/document/doctest.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,9 +16,11 @@ const globalAttr = "global"

func (proc *Processor) extractDocTests() error {
proc.docTests = []*docTest{}
return proc.walkAllDocStrings(proc.Docs, proc.extractTests, func(elem Named) string {
return elem.GetFileName()
})
w := walker{
Func: proc.extractTests,
NameFunc: func(elem Named) string { return elem.GetFileName() },
}
return w.walkAllDocStrings(proc.Docs)
}

func (proc *Processor) extractDocTestsMarkdown(baseDir string, build bool) error {
Expand Down Expand Up @@ -76,7 +78,7 @@ func (proc *Processor) extractMarkdown(file, baseDir, outDir string, build bool)
if err != nil {
return err
}
return proc.WriteFile(targetPath, contentStr)
return proc.writeFile(targetPath, contentStr)
}
return nil
}
Expand All @@ -101,7 +103,7 @@ func (proc *Processor) writeDocTests(dir string) error {
return err
}

err = proc.WriteFile(fullPath, b.String())
err = proc.writeFile(fullPath, b.String())
if err != nil {
return err
}
Expand Down
93 changes: 54 additions & 39 deletions internal/document/document.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -15,11 +15,13 @@ const capitalFileMarker = "-"
// TODO: find another way to handle this, without using a global variable.
var caseSensitiveSystem = true

// Docs holds the document for a package.
type Docs struct {
Decl *Package
Version string
}

// Package holds the document for a package.
type Package struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -35,29 +37,30 @@ type Package struct {
MemberLink `yaml:"-" json:"-"`
}

func (p *Package) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
// checkMissing checks for missing documentation.
func (p *Package) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := p.Name
if len(path) > 0 {
newPath = fmt.Sprintf("%s.%s", path, p.Name)
}
missing = p.MemberSummary.CheckMissing(newPath, stats)
missing = p.MemberSummary.checkMissing(newPath, stats)
for _, e := range p.Packages {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range p.Modules {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range p.Aliases {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range p.Structs {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range p.Traits {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range p.Functions {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
return missing
}
Expand All @@ -73,6 +76,7 @@ func (p *Package) linkedCopy() *Package {
}
}

// Module holds the document for a module.
type Module struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -85,24 +89,25 @@ type Module struct {
MemberLink `yaml:"-" json:"-"`
}

func (m *Module) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (m *Module) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := fmt.Sprintf("%s.%s", path, m.Name)
missing = m.MemberSummary.CheckMissing(newPath, stats)
missing = m.MemberSummary.checkMissing(newPath, stats)
for _, e := range m.Aliases {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range m.Structs {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range m.Traits {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range m.Functions {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
return missing
}

// Alias holds the document for an alias.
type Alias struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -112,11 +117,12 @@ type Alias struct {
Deprecated string
}

func (a *Alias) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (a *Alias) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := fmt.Sprintf("%s.%s", path, a.Name)
return a.MemberSummary.CheckMissing(newPath, stats)
return a.MemberSummary.checkMissing(newPath, stats)
}

// Struct holds the document for a struct.
type Struct struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -134,24 +140,25 @@ type Struct struct {
MemberLink `yaml:"-" json:"-"`
}

func (s *Struct) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (s *Struct) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := fmt.Sprintf("%s.%s", path, s.Name)
missing = s.MemberSummary.CheckMissing(newPath, stats)
missing = s.MemberSummary.checkMissing(newPath, stats)
for _, e := range s.Aliases {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range s.Fields {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range s.Parameters {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range s.Functions {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
return missing
}

// Function holds the document for a function.
type Function struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -174,10 +181,10 @@ type Function struct {
MemberLink `yaml:"-" json:"-"`
}

func (f *Function) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (f *Function) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
if len(f.Overloads) == 0 {
newPath := fmt.Sprintf("%s.%s", path, f.Name)
missing = f.MemberSummary.CheckMissing(newPath, stats)
missing = f.MemberSummary.checkMissing(newPath, stats)
if f.Raises && f.RaisesDoc == "" {
missing = append(missing, missingDocs{newPath, "raises docs"})
stats.Missing++
Expand All @@ -189,19 +196,20 @@ func (f *Function) CheckMissing(path string, stats *missingStats) (missing []mis
stats.Total += 2

for _, e := range f.Parameters {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range f.Args {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
return missing
}
for _, o := range f.Overloads {
missing = append(missing, o.CheckMissing(path, stats)...)
missing = append(missing, o.checkMissing(path, stats)...)
}
return missing
}

// Field holds the document for a field.
type Field struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -210,11 +218,12 @@ type Field struct {
Type string
}

func (f *Field) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (f *Field) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := fmt.Sprintf("%s.%s", path, f.Name)
return f.MemberSummary.CheckMissing(newPath, stats)
return f.MemberSummary.checkMissing(newPath, stats)
}

// Trait holds the document for a trait.
type Trait struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -227,18 +236,19 @@ type Trait struct {
MemberLink `yaml:"-" json:"-"`
}

func (t *Trait) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (t *Trait) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
newPath := fmt.Sprintf("%s.%s", path, t.Name)
missing = t.MemberSummary.CheckMissing(newPath, stats)
missing = t.MemberSummary.checkMissing(newPath, stats)
for _, e := range t.Fields {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
for _, e := range t.Functions {
missing = append(missing, e.CheckMissing(newPath, stats)...)
missing = append(missing, e.checkMissing(newPath, stats)...)
}
return missing
}

// Arg holds the document for a function argument.
type Arg struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -249,7 +259,7 @@ type Arg struct {
Default string
}

func (a *Arg) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (a *Arg) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
if a.Name == "self" && (a.Type == "Self" || a.Type == "_Self") {
return nil
}
Expand All @@ -264,6 +274,7 @@ func (a *Arg) CheckMissing(path string, stats *missingStats) (missing []missingD
return missing
}

// Parameter holds the document for a parameter.
type Parameter struct {
MemberKind `yaml:",inline"`
MemberName `yaml:",inline"`
Expand All @@ -273,7 +284,7 @@ type Parameter struct {
Default string
}

func (p *Parameter) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
func (p *Parameter) checkMissing(path string, stats *missingStats) (missing []missingDocs) {
if p.Description == "" {
missing = append(missing, missingDocs{fmt.Sprintf("%s.%s", path, p.Name), "description"})
stats.Missing++
Expand All @@ -282,7 +293,8 @@ func (p *Parameter) CheckMissing(path string, stats *missingStats) (missing []mi
return missing
}

func FromJson(data []byte) (*Docs, error) {
// FromJSON parses JSON documentation.
func FromJSON(data []byte) (*Docs, error) {
reader := bytes.NewReader(data)
dec := json.NewDecoder(reader)
dec.DisallowUnknownFields()
Expand All @@ -298,7 +310,8 @@ func FromJson(data []byte) (*Docs, error) {
return &docs, nil
}

func (d *Docs) ToJson() ([]byte, error) {
// ToJSON converts the documentation to JSON.
func (d *Docs) ToJSON() ([]byte, error) {
b := bytes.Buffer{}
enc := json.NewEncoder(&b)
enc.SetIndent("", " ")
Expand All @@ -309,7 +322,8 @@ func (d *Docs) ToJson() ([]byte, error) {
return b.Bytes(), nil
}

func FromYaml(data []byte) (*Docs, error) {
// FromYAML parses YAML documentation.
func FromYAML(data []byte) (*Docs, error) {
reader := bytes.NewReader(data)
dec := yaml.NewDecoder(reader)
dec.KnownFields(true)
Expand All @@ -325,7 +339,8 @@ func FromYaml(data []byte) (*Docs, error) {
return &docs, nil
}

func (d *Docs) ToYaml() ([]byte, error) {
// ToYAML converts the documentation to YAML.
func (d *Docs) ToYAML() ([]byte, error) {
b := bytes.Buffer{}
enc := yaml.NewEncoder(&b)

Expand Down
Loading

0 comments on commit 8b2bd88

Please sign in to comment.