Skip to content

Commit

Permalink
fix linter warnings, add docstings
Browse files Browse the repository at this point in the history
  • Loading branch information
@mlange-42
mlange-42 committed Feb 9, 2025
1 parent 68430a0 commit 803bdc4
Show file tree
Hide file tree
Showing 13 changed files with 107 additions and 62 deletions.
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
4 changes: 2 additions & 2 deletions internal/document/doctest.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -78,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 @@ -103,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
10 changes: 5 additions & 5 deletions internal/document/document_test.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -20,13 +20,13 @@ func TestFromJson(t *testing.T) {
"version": "0.1.0"
}`

docs, err := FromJson([]byte(data))
docs, err := FromJSON([]byte(data))
assert.Nil(t, err)
assert.NotNil(t, docs)

outJson, err := docs.ToJson()
outJSON, err := docs.ToJSON()
assert.Nil(t, err)
fmt.Println(string(outJson))
fmt.Println(string(outJSON))
}

func TestFromYaml(t *testing.T) {
Expand All @@ -43,13 +43,13 @@ decl:
version: 0.1.0
`

docs, err := FromYaml([]byte(data))
docs, err := FromYAML([]byte(data))
assert.Nil(t, err)
assert.NotNil(t, docs)

assert.Equal(t, "Struct", docs.Decl.Modules[0].Structs[0].Name)

outYaml, err := docs.ToYaml()
outYaml, err := docs.ToYAML()
assert.Nil(t, err)
fmt.Println(string(outYaml))
}
Expand Down
1 change: 1 addition & 0 deletions internal/document/format.go
View file
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ type Formatter interface {
Clean(out, tests string) error
}

// PackageSource represents a sources of a package.
type PackageSource struct {
Name string
Path []string
Expand Down
Loading

0 comments on commit 803bdc4

Please sign in to comment.