diff --git a/go.mod b/go.mod index 42937b8..52fb929 100644 --- a/go.mod +++ b/go.mod @@ -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 diff --git a/go.sum b/go.sum index 2176312..005ec17 100644 --- a/go.sum +++ b/go.sum @@ -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= diff --git a/internal/cmd/util.go b/internal/cmd/util.go index eeb1ade..824b657 100644 --- a/internal/cmd/util.go +++ b/internal/cmd/util.go @@ -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) { diff --git a/internal/document/config.go b/internal/document/config.go index 8b36bd8..4d42c09 100644 --- a/internal/document/config.go +++ b/internal/document/config.go @@ -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"` @@ -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 { @@ -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 diff --git a/internal/document/doctest.go b/internal/document/doctest.go index 62fd557..0cf0321 100644 --- a/internal/document/doctest.go +++ b/internal/document/doctest.go @@ -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 { @@ -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 } @@ -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 } diff --git a/internal/document/document.go b/internal/document/document.go index 8e80306..7fbe431 100644 --- a/internal/document/document.go +++ b/internal/document/document.go @@ -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"` @@ -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 } @@ -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"` @@ -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"` @@ -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"` @@ -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"` @@ -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++ @@ -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"` @@ -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"` @@ -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"` @@ -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 } @@ -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"` @@ -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++ @@ -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() @@ -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("", " ") @@ -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) @@ -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) diff --git a/internal/document/document_test.go b/internal/document/document_test.go index bdb0493..9ec6cc3 100644 --- a/internal/document/document_test.go +++ b/internal/document/document_test.go @@ -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) { @@ -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)) } diff --git a/internal/document/format.go b/internal/document/format.go index 580effb..9a58302 100644 --- a/internal/document/format.go +++ b/internal/document/format.go @@ -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 diff --git a/internal/document/interface.go b/internal/document/interface.go index 30fb6ca..0b68cb5 100644 --- a/internal/document/interface.go +++ b/internal/document/interface.go @@ -15,24 +15,29 @@ type missingStats struct { Missing int } +// Kinded is an interface for types that have a kind. type Kinded interface { GetKind() string } +// Named is an interface for types that have a name. type Named interface { GetName() string GetFileName() string } +// Summarized is an interface for types that have a summary. type Summarized interface { GetSummary() string } +// Linked is an interface for types that can be linked/referenced. type Linked interface { SetLink(path []string, kind string) GetLink() string } +// MemberKind holds the kind of a member. type MemberKind struct { Kind string } @@ -41,10 +46,12 @@ func newKind(kind string) MemberKind { return MemberKind{Kind: kind} } +// GetKind returns the kind of the member. func (m *MemberKind) GetKind() string { return m.Kind } +// MemberName holds the name of a member. type MemberName struct { Name string } @@ -53,14 +60,17 @@ func newName(name string) MemberName { return MemberName{Name: name} } +// GetName returns the name of the member. func (m *MemberName) GetName() string { return m.Name } +// GetFileName returns the file name of the member. func (m *MemberName) GetFileName() string { return toFileName(m.Name) } +// MemberSummary holds the summary of a member. type MemberSummary struct { Summary string } @@ -69,11 +79,12 @@ func newSummary(summary string) *MemberSummary { return &MemberSummary{Summary: summary} } +// GetSummary returns the summary of the member. func (m *MemberSummary) GetSummary() string { return m.Summary } -func (m *MemberSummary) CheckMissing(path string, stats *missingStats) (missing []missingDocs) { +func (m *MemberSummary) checkMissing(path string, stats *missingStats) (missing []missingDocs) { if m.Summary == "" { missing = append(missing, missingDocs{path, "description"}) stats.Missing++ @@ -82,6 +93,7 @@ func (m *MemberSummary) CheckMissing(path string, stats *missingStats) (missing return missing } +// MemberDescription holds the description of a member. type MemberDescription struct { Description string } @@ -90,6 +102,7 @@ func newDescription(description string) *MemberDescription { return &MemberDescription{Description: description} } +// GetDescription returns the description of the member. func (m *MemberDescription) GetDescription() string { return m.Description } @@ -102,10 +115,12 @@ func isCap(s string) bool { return unicode.IsUpper(firstRune) } +// MemberLink holds the link of a member. type MemberLink struct { Link string } +// SetLink sets the link of the member. func (m *MemberLink) SetLink(p []string, kind string) { if kind == "package" { m.Link = path.Join(path.Join(p[1:]...), "__init__.mojo") @@ -114,6 +129,7 @@ func (m *MemberLink) SetLink(p []string, kind string) { } } +// GetLink returns the link of the member. func (m *MemberLink) GetLink() string { return m.Link } diff --git a/internal/document/links.go b/internal/document/links.go index 5163321..4fcb77d 100644 --- a/internal/document/links.go +++ b/internal/document/links.go @@ -26,9 +26,11 @@ func init() { } func (proc *Processor) processLinks(docs *Docs) error { - return proc.walkAllDocStrings(docs, proc.replaceRefs, func(elem Named) string { - return elem.GetName() - }) + w := walker{ + Func: proc.replaceRefs, + NameFunc: func(elem Named) string { return elem.GetName() }, + } + return w.walkAllDocStrings(docs) } func (proc *Processor) replaceRefs(text string, elems []string, modElems int) (string, error) { @@ -55,6 +57,7 @@ func (proc *Processor) replaceRefs(text string, elems []string, modElems int) (s return text, nil } +// ReplacePlaceholders replaces placeholders in the text with links to the corresponding elements. func (proc *Processor) ReplacePlaceholders(text string, elems []string, modElems int) (string, error) { indices, err := findLinks(text, linkRegex, true) if err != nil { @@ -156,7 +159,7 @@ func (proc *Processor) renameInLink(link string, elems *elemPath) string { maxDepth := len(elems.Elements) if elems.IsSection { - maxDepth -= 1 + maxDepth-- } newLink := strings.Split(link, ".") @@ -206,9 +209,8 @@ func (proc *Processor) refToPlaceholder(link string, elems []string, modElems in if len(linkParts) > 1 { return fmt.Sprintf("%s %s", placeholder, linkParts[1]), true, nil - } else { - return placeholder, true, nil } + return placeholder, true, nil } func (proc *Processor) refToPlaceholderRel(link string, elems []string, modElems int, redirect bool) (string, bool, error) { diff --git a/internal/document/processor.go b/internal/document/processor.go index cca3a94..ba526d2 100644 --- a/internal/document/processor.go +++ b/internal/document/processor.go @@ -8,6 +8,7 @@ import ( "text/template" ) +// Processor is the main struct for processing and rendering documentation. type Processor struct { Config *Config Template *template.Template @@ -35,12 +36,14 @@ type docTest struct { Global []string } +// NewProcessor creates a new Processor instance. func NewProcessor(docs *Docs, f Formatter, t *template.Template, config *Config) *Processor { return NewProcessorWithWriter(docs, f, t, config, func(file, text string) error { return os.WriteFile(file, []byte(text), 0644) }) } +// NewProcessorWithWriter creates a new Processor instance with a custom writer. func NewProcessorWithWriter(docs *Docs, f Formatter, t *template.Template, config *Config, writer func(file, text string) error) *Processor { return &Processor{ Config: config, @@ -85,6 +88,7 @@ func (proc *Processor) PrepareDocs(subdir string) error { return nil } +// ExtractTests extracts and writes doc tests. func (proc *Processor) ExtractTests(subdir string) error { // Collect the paths of all (sub)-elements in the original structure. proc.collectElementPaths() @@ -105,7 +109,7 @@ func (proc *Processor) ExtractTests(subdir string) error { return nil } -func (proc *Processor) WriteFile(file, text string) error { +func (proc *Processor) writeFile(file, text string) error { return proc.writer(file, text) } diff --git a/internal/document/render.go b/internal/document/render.go index a72c71d..ca2a8fc 100644 --- a/internal/document/render.go +++ b/internal/document/render.go @@ -6,6 +6,7 @@ import ( "strings" ) +// Render generates documentation for the given docs and writes it to the output directory. func Render(docs *Docs, config *Config, form Formatter, subdir string) error { t, err := LoadTemplates(form, config.SourceURLs[strings.ToLower(docs.Decl.Name)], config.TemplateDirs...) if err != nil { @@ -33,6 +34,7 @@ func Render(docs *Docs, config *Config, form Formatter, subdir string) error { return nil } +// ExtractTests extracts tests from the documentation. func ExtractTests(docs *Docs, config *Config, form Formatter, subdir string) error { caseSensitiveSystem = !config.CaseInsensitive t, err := LoadTemplates(form, config.SourceURLs[strings.ToLower(docs.Decl.Name)], config.TemplateDirs...) @@ -50,6 +52,7 @@ func ExtractTests(docs *Docs, config *Config, form Formatter, subdir string) err return proc.ExtractTests(subdir) } +// ExtractTestsMarkdown extracts tests from markdown files. func ExtractTestsMarkdown(config *Config, form Formatter, baseDir string, build bool) error { caseSensitiveSystem = !config.CaseInsensitive @@ -77,7 +80,7 @@ func renderWith(config *Config, proc *Processor, subdir string) error { var missing []missingDocs var stats missingStats if config.ReportMissing { - missing = proc.Docs.Decl.CheckMissing("", &stats) + missing = proc.Docs.Decl.checkMissing("", &stats) } outPath := path.Join(config.OutputDir, subdir) @@ -197,7 +200,7 @@ func linkAndWrite(text string, dir []string, modElems int, kind string, proc *Pr return err } outFile := proc.Formatter.ToFilePath(path.Join(dir...), kind) - return proc.WriteFile(outFile, text) + return proc.writeFile(outFile, text) } func reportMissing(pkg string, missing []missingDocs, stats missingStats, strict bool) error { diff --git a/internal/document/render_test.go b/internal/document/render_test.go index 4aeb693..9f84bd9 100644 --- a/internal/document/render_test.go +++ b/internal/document/render_test.go @@ -115,7 +115,7 @@ decl: - name: func2 kind: function ` - docs, err := FromYaml([]byte(yml)) + docs, err := FromYAML([]byte(yml)) assert.Nil(t, err) assert.NotNil(t, docs) @@ -169,7 +169,7 @@ decl: kind: argument description: A description ` - docs, err := FromYaml([]byte(yml)) + docs, err := FromYAML([]byte(yml)) assert.Nil(t, err) assert.NotNil(t, docs) @@ -214,7 +214,7 @@ decl: kind: argument description: A description ` - docs, err := FromYaml([]byte(yml)) + docs, err := FromYAML([]byte(yml)) assert.Nil(t, err) assert.NotNil(t, docs) @@ -251,7 +251,7 @@ decl: kind: argument description: A description ` - docs, err := FromYaml([]byte(yml)) + docs, err := FromYAML([]byte(yml)) assert.Nil(t, err) assert.NotNil(t, docs) @@ -287,7 +287,7 @@ func TestRenderDry(t *testing.T) { data, err := os.ReadFile(config.InputFiles[0]) assert.Nil(t, err) - doc, err := FromJson(data) + doc, err := FromJSON(data) assert.Nil(t, err) err = Render(doc, &config, &formatter, "") @@ -315,7 +315,7 @@ func TestRenderFiles(t *testing.T) { data, err := os.ReadFile(path.Join(config.InputFiles[0], "test.json")) assert.Nil(t, err) - doc, err := FromJson(data) + doc, err := FromJSON(data) assert.Nil(t, err) err = Render(doc, &config, &formatter, "") diff --git a/internal/document/util.go b/internal/document/util.go index 56b30d5..756e24f 100644 --- a/internal/document/util.go +++ b/internal/document/util.go @@ -23,6 +23,7 @@ const ( fenceFour ) +// GitInfo contains information about a Git repository. type GitInfo struct { Title string Repo string @@ -58,6 +59,7 @@ func warnOrError(strict bool, pattern string, args ...any) error { return nil } +// LoadTemplates loads all templates from the assets and additional directories. func LoadTemplates(f Formatter, sourceURL string, additional ...string) (*template.Template, error) { templ := template.New("all") templ = templ.Funcs(template.FuncMap{ @@ -120,6 +122,7 @@ func findTemplates(dir string) ([]string, error) { return allTemplates, nil } +// GetGitOrigin tries to determine the `origin` remote repository. func GetGitOrigin(outDir string) (*GitInfo, error) { gitFiles := []string{ ".git/config", diff --git a/internal/document/walk_docs.go b/internal/document/walk_docs.go index 31649d0..ef0eb3a 100644 --- a/internal/document/walk_docs.go +++ b/internal/document/walk_docs.go @@ -3,129 +3,134 @@ package document type walkFunc = func(text string, elems []string, modElems int) (string, error) type nameFunc = func(elem Named) string -func (proc *Processor) walkAllDocStrings(docs *Docs, fn walkFunc, nameFn nameFunc) error { - return proc.walkAllDocStringsPackage(docs.Decl, []string{}, fn, nameFn) +type walker struct { + Func walkFunc + NameFunc nameFunc } -func (proc *Processor) walkAllDocStringsPackage(p *Package, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(p)) +func (w *walker) walkAllDocStrings(docs *Docs) error { + return w.walkAllDocStringsPackage(docs.Decl, []string{}) +} + +func (w *walker) walkAllDocStringsPackage(p *Package, elems []string) error { + newElems := appendNew(elems, w.NameFunc(p)) var err error - if p.Summary, err = fn(p.Summary, newElems, len(newElems)); err != nil { + if p.Summary, err = w.Func(p.Summary, newElems, len(newElems)); err != nil { return err } - if p.Description, err = fn(p.Description, newElems, len(newElems)); err != nil { + if p.Description, err = w.Func(p.Description, newElems, len(newElems)); err != nil { return err } for _, pkg := range p.Packages { - if err := proc.walkAllDocStringsPackage(pkg, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsPackage(pkg, newElems); err != nil { return err } } for _, mod := range p.Modules { - if err := proc.walkAllDocStringsModule(mod, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsModule(mod, newElems); err != nil { return err } } for _, a := range p.Aliases { - if err := proc.walkAllDocStringsModuleAlias(a, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsModuleAlias(a, newElems); err != nil { return err } } for _, f := range p.Functions { - if err := proc.walkAllDocStringsFunction(f, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsFunction(f, newElems); err != nil { return err } } for _, s := range p.Structs { - if err := proc.walkAllDocStringsStruct(s, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsStruct(s, newElems); err != nil { return err } } for _, tr := range p.Traits { - if err := proc.walkAllDocStringsTrait(tr, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsTrait(tr, newElems); err != nil { return err } } return nil } -func (proc *Processor) walkAllDocStringsModule(m *Module, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(m)) +func (w *walker) walkAllDocStringsModule(m *Module, elems []string) error { + newElems := appendNew(elems, w.NameFunc(m)) var err error - if m.Summary, err = fn(m.Summary, newElems, len(newElems)); err != nil { + if m.Summary, err = w.Func(m.Summary, newElems, len(newElems)); err != nil { return err } - if m.Description, err = fn(m.Description, newElems, len(newElems)); err != nil { + if m.Description, err = w.Func(m.Description, newElems, len(newElems)); err != nil { return err } for _, a := range m.Aliases { - if err := proc.walkAllDocStringsModuleAlias(a, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsModuleAlias(a, newElems); err != nil { return err } } for _, f := range m.Functions { - if err := proc.walkAllDocStringsFunction(f, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsFunction(f, newElems); err != nil { return err } } for _, s := range m.Structs { - if err := proc.walkAllDocStringsStruct(s, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsStruct(s, newElems); err != nil { return err } } for _, tr := range m.Traits { - if err := proc.walkAllDocStringsTrait(tr, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsTrait(tr, newElems); err != nil { return err } } return nil } -func (proc *Processor) walkAllDocStringsStruct(s *Struct, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(s)) +func (w *walker) walkAllDocStringsStruct(s *Struct, elems []string) error { + newElems := appendNew(elems, w.NameFunc(s)) var err error - if s.Summary, err = fn(s.Summary, newElems, len(elems)); err != nil { + if s.Summary, err = w.Func(s.Summary, newElems, len(elems)); err != nil { return err } - if s.Description, err = fn(s.Description, newElems, len(elems)); err != nil { + if s.Description, err = w.Func(s.Description, newElems, len(elems)); err != nil { return err } - if s.Deprecated, err = fn(s.Deprecated, newElems, len(elems)); err != nil { + if s.Deprecated, err = w.Func(s.Deprecated, newElems, len(elems)); err != nil { return err } for _, a := range s.Aliases { - if a.Summary, err = fn(a.Summary, newElems, len(elems)); err != nil { + if a.Summary, err = w.Func(a.Summary, newElems, len(elems)); err != nil { return err } - if a.Description, err = fn(a.Description, newElems, len(elems)); err != nil { + if a.Description, err = w.Func(a.Description, newElems, len(elems)); err != nil { return err } - if a.Deprecated, err = fn(a.Deprecated, newElems, len(elems)); err != nil { + if a.Deprecated, err = w.Func(a.Deprecated, newElems, len(elems)); err != nil { return err } } for _, p := range s.Parameters { - if p.Description, err = fn(p.Description, newElems, len(elems)); err != nil { + if p.Description, err = w.Func(p.Description, newElems, len(elems)); err != nil { return err } } for _, f := range s.Fields { - if f.Summary, err = fn(f.Summary, newElems, len(elems)); err != nil { + if f.Summary, err = w.Func(f.Summary, newElems, len(elems)); err != nil { return err } - if f.Description, err = fn(f.Description, newElems, len(elems)); err != nil { + if f.Description, err = w.Func(f.Description, newElems, len(elems)); err != nil { return err } } for _, f := range s.Functions { - if err := proc.walkAllDocStringsMethod(f, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsMethod(f, newElems); err != nil { return err } } @@ -133,17 +138,17 @@ func (proc *Processor) walkAllDocStringsStruct(s *Struct, elems []string, fn wal return nil } -func (proc *Processor) walkAllDocStringsTrait(tr *Trait, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(tr)) +func (w *walker) walkAllDocStringsTrait(tr *Trait, elems []string) error { + newElems := appendNew(elems, w.NameFunc(tr)) var err error - if tr.Summary, err = fn(tr.Summary, newElems, len(elems)); err != nil { + if tr.Summary, err = w.Func(tr.Summary, newElems, len(elems)); err != nil { return err } - if tr.Description, err = fn(tr.Description, newElems, len(elems)); err != nil { + if tr.Description, err = w.Func(tr.Description, newElems, len(elems)); err != nil { return err } - if tr.Deprecated, err = fn(tr.Deprecated, newElems, len(elems)); err != nil { + if tr.Deprecated, err = w.Func(tr.Deprecated, newElems, len(elems)); err != nil { return err } @@ -155,15 +160,15 @@ func (proc *Processor) walkAllDocStringsTrait(tr *Trait, elems []string, fn walk } }*/ for _, f := range tr.Fields { - if f.Summary, err = fn(f.Summary, newElems, len(elems)); err != nil { + if f.Summary, err = w.Func(f.Summary, newElems, len(elems)); err != nil { return err } - if f.Description, err = fn(f.Description, newElems, len(elems)); err != nil { + if f.Description, err = w.Func(f.Description, newElems, len(elems)); err != nil { return err } } for _, f := range tr.Functions { - if err := proc.walkAllDocStringsMethod(f, newElems, fn, nameFn); err != nil { + if err := w.walkAllDocStringsMethod(f, newElems); err != nil { return err } } @@ -171,39 +176,39 @@ func (proc *Processor) walkAllDocStringsTrait(tr *Trait, elems []string, fn walk return nil } -func (proc *Processor) walkAllDocStringsFunction(f *Function, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(f)) +func (w *walker) walkAllDocStringsFunction(f *Function, elems []string) error { + newElems := appendNew(elems, w.NameFunc(f)) var err error - if f.Summary, err = fn(f.Summary, newElems, len(elems)); err != nil { + if f.Summary, err = w.Func(f.Summary, newElems, len(elems)); err != nil { return err } - if f.Description, err = fn(f.Description, newElems, len(elems)); err != nil { + if f.Description, err = w.Func(f.Description, newElems, len(elems)); err != nil { return err } - if f.Deprecated, err = fn(f.Deprecated, newElems, len(elems)); err != nil { + if f.Deprecated, err = w.Func(f.Deprecated, newElems, len(elems)); err != nil { return err } - if f.ReturnsDoc, err = fn(f.ReturnsDoc, newElems, len(elems)); err != nil { + if f.ReturnsDoc, err = w.Func(f.ReturnsDoc, newElems, len(elems)); err != nil { return err } - if f.RaisesDoc, err = fn(f.RaisesDoc, newElems, len(elems)); err != nil { + if f.RaisesDoc, err = w.Func(f.RaisesDoc, newElems, len(elems)); err != nil { return err } for _, a := range f.Args { - if a.Description, err = fn(a.Description, newElems, len(elems)); err != nil { + if a.Description, err = w.Func(a.Description, newElems, len(elems)); err != nil { return err } } for _, p := range f.Parameters { - if p.Description, err = fn(p.Description, newElems, len(elems)); err != nil { + if p.Description, err = w.Func(p.Description, newElems, len(elems)); err != nil { return err } } for _, o := range f.Overloads { - err := proc.walkAllDocStringsFunction(o, elems, fn, nameFn) + err := w.walkAllDocStringsFunction(o, elems) if err != nil { return err } @@ -212,53 +217,53 @@ func (proc *Processor) walkAllDocStringsFunction(f *Function, elems []string, fn return nil } -func (proc *Processor) walkAllDocStringsModuleAlias(a *Alias, elems []string, fn walkFunc, nameFn nameFunc) error { - newElems := appendNew(elems, nameFn(a)) +func (w *walker) walkAllDocStringsModuleAlias(a *Alias, elems []string) error { + newElems := appendNew(elems, w.NameFunc(a)) var err error - if a.Summary, err = fn(a.Summary, newElems, len(elems)); err != nil { + if a.Summary, err = w.Func(a.Summary, newElems, len(elems)); err != nil { return err } - if a.Description, err = fn(a.Description, newElems, len(elems)); err != nil { + if a.Description, err = w.Func(a.Description, newElems, len(elems)); err != nil { return err } - if a.Deprecated, err = fn(a.Deprecated, newElems, len(elems)); err != nil { + if a.Deprecated, err = w.Func(a.Deprecated, newElems, len(elems)); err != nil { return err } return nil } -func (proc *Processor) walkAllDocStringsMethod(f *Function, elems []string, fn walkFunc, nameFn nameFunc) error { +func (w *walker) walkAllDocStringsMethod(f *Function, elems []string) error { var err error - if f.Summary, err = fn(f.Summary, elems, len(elems)-1); err != nil { + if f.Summary, err = w.Func(f.Summary, elems, len(elems)-1); err != nil { return err } - if f.Description, err = fn(f.Description, elems, len(elems)-1); err != nil { + if f.Description, err = w.Func(f.Description, elems, len(elems)-1); err != nil { return err } - if f.Deprecated, err = fn(f.Deprecated, elems, len(elems)-1); err != nil { + if f.Deprecated, err = w.Func(f.Deprecated, elems, len(elems)-1); err != nil { return err } - if f.ReturnsDoc, err = fn(f.ReturnsDoc, elems, len(elems)-1); err != nil { + if f.ReturnsDoc, err = w.Func(f.ReturnsDoc, elems, len(elems)-1); err != nil { return err } - if f.RaisesDoc, err = fn(f.RaisesDoc, elems, len(elems)-1); err != nil { + if f.RaisesDoc, err = w.Func(f.RaisesDoc, elems, len(elems)-1); err != nil { return err } for _, a := range f.Args { - if a.Description, err = fn(a.Description, elems, len(elems)-1); err != nil { + if a.Description, err = w.Func(a.Description, elems, len(elems)-1); err != nil { return err } } for _, p := range f.Parameters { - if p.Description, err = fn(p.Description, elems, len(elems)-1); err != nil { + if p.Description, err = w.Func(p.Description, elems, len(elems)-1); err != nil { return err } } for _, o := range f.Overloads { - err := proc.walkAllDocStringsMethod(o, elems, fn, nameFn) + err := w.walkAllDocStringsMethod(o, elems) if err != nil { return err } diff --git a/test/profile/stdlib/main.go b/test/profile/stdlib/main.go index 48d3055..e5fb578 100644 --- a/test/profile/stdlib/main.go +++ b/test/profile/stdlib/main.go @@ -51,7 +51,7 @@ func run(file string, iters int) { } formatter := format.Plain{} - doc, err := document.FromJson(data) + doc, err := document.FromJSON(data) if err != nil { panic(err) }