14250580349

Committed 03 Apr 2025 06:52PM CUT coverage: 74.237%. Remained the same

Build # 14250580349

Build Type

Pull #233

github

Committed by

web-flow

Commit Message

Merge 6642a250c into 1f8e6af6a

Pull Request Pull Request #233: Don't warn on missing docs for `self` arguments

Run Details

1 of 1 new or added line in 1 file covered. (100.0%)

2383 of 3210 relevant lines covered (74.24%)

48.18 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

62.5

/internal/document/render.go

package document

import (
        "fmt"
        "path"
        "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 {
                return err
        }
        if !config.DryRun {
                proc := NewProcessor(docs, form, t, config)
                return renderWith(config, proc, subdir)
        }

        files := []string{}
        proc := NewProcessorWithWriter(docs, form, t, config, func(file, text string) error {
                files = append(files, file)
                return nil
        })
        err = renderWith(config, proc, subdir)
        if err != nil {
                return err
        }

        fmt.Println("Dry-run. Would write these files:")
        for _, f := range files {
                fmt.Println(f)
        }
        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...)
        if err != nil {
                return err
        }
        var proc *Processor
        if config.DryRun {
                proc = NewProcessorWithWriter(docs, form, t, config, func(file, text string) error {
                        return nil
                })
        } else {
                proc = NewProcessor(docs, form, t, config)
        }
        return proc.ExtractTests(subdir)
}

// ExtractTestsMarkdown extracts tests from markdown files.
func ExtractTestsMarkdown(config *Config, form Formatter, baseDir string, build bool) error {
        caseSensitiveSystem = !config.CaseInsensitive

        t, err := LoadTemplates(form, "", config.TemplateDirs...)
        if err != nil {
                return err
        }
        var proc *Processor
        if config.DryRun {
                proc = NewProcessorWithWriter(nil, form, t, config, func(file, text string) error {
                        return nil
                })
        } else {
                proc = NewProcessor(nil, form, t, config)
        }
        return proc.extractDocTestsMarkdown(baseDir, build)
}

func renderWith(config *Config, proc *Processor, subdir string) error {
        caseSensitiveSystem = !config.CaseInsensitive

        if err := proc.PrepareDocs(subdir); err != nil {
                return err
        }
        var missing []missingDocs
        var stats missingStats
        if config.ReportMissing {
                missing = proc.Docs.Decl.checkMissing("", &stats)
        }

        outPath := path.Join(config.OutputDir, subdir)
        if err := renderPackage(proc.ExportDocs.Decl, []string{outPath}, proc); err != nil {
                return err
        }
        if err := proc.Formatter.WriteAuxiliary(proc.ExportDocs.Decl, outPath, proc); err != nil {
                return err
        }
        if config.ReportMissing {
                if err := reportMissing(proc.Docs.Decl.Name, missing, stats, config.Strict); err != nil {
                        return err
                }
        }
        return nil
}

func renderElement(data interface {
        Named
        Kinded
}, proc *Processor) (string, error) {
        b := strings.Builder{}
        err := proc.Template.ExecuteTemplate(&b, data.GetKind()+".md", data)
        if err != nil {
                return "", err
        }
        return proc.Formatter.ProcessMarkdown(data, b.String(), proc)
}

func renderPackage(p *Package, dir []string, proc *Processor) error {
        newDir := appendNew(dir, p.GetFileName())
        pkgPath := path.Join(newDir...)
        if err := proc.mkDirs(pkgPath); err != nil {
                return err
        }

        for _, pkg := range p.Packages {
                if err := renderPackage(pkg, newDir, proc); err != nil {
                        return err
                }
        }

        for _, mod := range p.Modules {
                if err := renderModule(mod, newDir, proc); err != nil {
                        return err
                }
        }

        if err := renderList(p.Structs, newDir, proc); err != nil {
                return err
        }
        if err := renderList(p.Traits, newDir, proc); err != nil {
                return err
        }
        if err := renderList(p.Functions, newDir, proc); err != nil {
                return err
        }

        text, err := renderElement(p, proc)
        if err != nil {
                return err
        }
        if err := linkAndWrite(text, newDir, len(newDir), "package", proc); err != nil {
                return err
        }

        return nil
}

func renderModule(mod *Module, dir []string, proc *Processor) error {
        newDir := appendNew(dir, mod.GetFileName())
        if err := proc.mkDirs(path.Join(newDir...)); err != nil {
                return err
        }

        if err := renderList(mod.Structs, newDir, proc); err != nil {
                return err
        }
        if err := renderList(mod.Traits, newDir, proc); err != nil {
                return err
        }
        if err := renderList(mod.Functions, newDir, proc); err != nil {
                return err
        }

        text, err := renderElement(mod, proc)
        if err != nil {
                return err
        }
        if err := linkAndWrite(text, newDir, len(newDir), "module", proc); err != nil {
                return err
        }

        return nil
}

func renderList[T interface {
        Named
        Kinded
}](list []T, dir []string, proc *Processor) error {
        for _, elem := range list {
                newDir := appendNew(dir, elem.GetFileName())
                text, err := renderElement(elem, proc)
                if err != nil {
                        return err
                }
                if err := linkAndWrite(text, newDir, len(dir), elem.GetKind(), proc); err != nil {
                        return err
                }
        }
        return nil
}

func linkAndWrite(text string, dir []string, modElems int, kind string, proc *Processor) error {
        text, err := proc.ReplacePlaceholders(text, dir[1:], modElems-1)
        if err != nil {
                return err
        }
        outFile := proc.Formatter.ToFilePath(path.Join(dir...), kind)
        return proc.writeFile(outFile, text)
}

func reportMissing(pkg string, missing []missingDocs, stats missingStats, strict bool) error {
        if len(missing) == 0 {
                fmt.Printf("Docstring coverage of package %s: 100%%\n", pkg)
                return nil
        }
        for _, m := range missing {
                fmt.Printf("WARNING: missing %s in %s\n", m.What, m.Who)
        }
        fmt.Printf("Docstring coverage package %s: %.1f%%\n", pkg, 100.0*float64(stats.Total-stats.Missing)/float64(stats.Total))
        if strict {
                return fmt.Errorf("missing docstrings in strict mode")
        }
        return nil
}

1	package document
2
3	import (
4	"fmt"
5	"path"
6	"strings"
7	)
8
9	// Render generates documentation for the given docs and writes it to the output directory.
10	func Render(docs Docs, config Config, form Formatter, subdir string) error {	5✔
11	t, err := LoadTemplates(form, config.SourceURLs[strings.ToLower(docs.Decl.Name)], config.TemplateDirs...)	5✔
12	if err != nil {	5✔
13	return err	×
14	}	×
15	if !config.DryRun {	9✔
16	proc := NewProcessor(docs, form, t, config)	4✔
17	return renderWith(config, proc, subdir)	4✔
18	}	4✔
19
20	files := []string{}	1✔
21	proc := NewProcessorWithWriter(docs, form, t, config, func(file, text string) error {	10✔
22	files = append(files, file)	9✔
23	return nil	9✔
24	})	9✔
25	err = renderWith(config, proc, subdir)	1✔
26	if err != nil {	1✔
27	return err	×
28	}	×
29
30	fmt.Println("Dry-run. Would write these files:")	1✔
31	for _, f := range files {	10✔
32	fmt.Println(f)	9✔
33	}	9✔
34	return nil	1✔
35	}
36
37	// ExtractTests extracts tests from the documentation.
38	func ExtractTests(docs Docs, config Config, form Formatter, subdir string) error {	1✔
39	caseSensitiveSystem = !config.CaseInsensitive	1✔
40	t, err := LoadTemplates(form, config.SourceURLs[strings.ToLower(docs.Decl.Name)], config.TemplateDirs...)	1✔
41	if err != nil {	1✔
42	return err	×
43	}	×
44	var proc *Processor	1✔
45	if config.DryRun {	1✔
46	proc = NewProcessorWithWriter(docs, form, t, config, func(file, text string) error {	×
47	return nil	×
48	})	×
49	} else {	1✔
50	proc = NewProcessor(docs, form, t, config)	1✔
51	}	1✔
52	return proc.ExtractTests(subdir)	1✔
53	}
54
55	// ExtractTestsMarkdown extracts tests from markdown files.
56	func ExtractTestsMarkdown(config *Config, form Formatter, baseDir string, build bool) error {	6✔
57	caseSensitiveSystem = !config.CaseInsensitive	6✔
58		6✔
59	t, err := LoadTemplates(form, "", config.TemplateDirs...)	6✔
60	if err != nil {	6✔
61	return err	×
62	}	×
63	var proc *Processor	6✔
64	if config.DryRun {	6✔
65	proc = NewProcessorWithWriter(nil, form, t, config, func(file, text string) error {	×
66	return nil	×
67	})	×
68	} else {	6✔
69	proc = NewProcessor(nil, form, t, config)	6✔
70	}	6✔
71	return proc.extractDocTestsMarkdown(baseDir, build)	6✔
72	}
73
74	func renderWith(config Config, proc Processor, subdir string) error {	9✔
75	caseSensitiveSystem = !config.CaseInsensitive	9✔
76		9✔
77	if err := proc.PrepareDocs(subdir); err != nil {	9✔
78	return err	×
79	}	×
80	var missing []missingDocs	9✔
81	var stats missingStats	9✔
82	if config.ReportMissing {	13✔
83	missing = proc.Docs.Decl.checkMissing("", &stats)	4✔
84	}	4✔
85
86	outPath := path.Join(config.OutputDir, subdir)	9✔
87	if err := renderPackage(proc.ExportDocs.Decl, []string{outPath}, proc); err != nil {	9✔
88	return err	×
89	}	×
90	if err := proc.Formatter.WriteAuxiliary(proc.ExportDocs.Decl, outPath, proc); err != nil {	9✔
91	return err	×
92	}	×
93	if config.ReportMissing {	13✔
94	if err := reportMissing(proc.Docs.Decl.Name, missing, stats, config.Strict); err != nil {	4✔
95	return err	×
96	}	×
97	}
98	return nil	9✔
99	}
100
101	func renderElement(data interface {
102	Named
103	Kinded
104	}, proc *Processor) (string, error) {	62✔
105	b := strings.Builder{}	62✔
106	err := proc.Template.ExecuteTemplate(&b, data.GetKind()+".md", data)	62✔
107	if err != nil {	62✔
108	return "", err	×
109	}	×
110	return proc.Formatter.ProcessMarkdown(data, b.String(), proc)	62✔
111	}
112
113	func renderPackage(p Package, dir []string, proc Processor) error {	14✔
114	newDir := appendNew(dir, p.GetFileName())	14✔
115	pkgPath := path.Join(newDir...)	14✔
116	if err := proc.mkDirs(pkgPath); err != nil {	14✔
117	return err	×
118	}	×
119
120	for _, pkg := range p.Packages {	19✔
121	if err := renderPackage(pkg, newDir, proc); err != nil {	5✔
122	return err	×
123	}	×
124	}
125
126	for _, mod := range p.Modules {	28✔
127	if err := renderModule(mod, newDir, proc); err != nil {	14✔
128	return err	×
129	}	×
130	}
131
132	if err := renderList(p.Structs, newDir, proc); err != nil {	14✔
133	return err	×
134	}	×
135	if err := renderList(p.Traits, newDir, proc); err != nil {	14✔
136	return err	×
137	}	×
138	if err := renderList(p.Functions, newDir, proc); err != nil {	14✔
139	return err	×
140	}	×
141
142	text, err := renderElement(p, proc)	14✔
143	if err != nil {	14✔
144	return err	×
145	}	×
146	if err := linkAndWrite(text, newDir, len(newDir), "package", proc); err != nil {	14✔
147	return err	×
148	}	×
149
150	return nil	14✔
151	}
152
153	func renderModule(mod Module, dir []string, proc Processor) error {	14✔
154	newDir := appendNew(dir, mod.GetFileName())	14✔
155	if err := proc.mkDirs(path.Join(newDir...)); err != nil {	14✔
156	return err	×
157	}	×
158
159	if err := renderList(mod.Structs, newDir, proc); err != nil {	14✔
160	return err	×
161	}	×
162	if err := renderList(mod.Traits, newDir, proc); err != nil {	14✔
163	return err	×
164	}	×
165	if err := renderList(mod.Functions, newDir, proc); err != nil {	14✔
166	return err	×
167	}	×
168
169	text, err := renderElement(mod, proc)	14✔
170	if err != nil {	14✔
171	return err	×
172	}	×
173	if err := linkAndWrite(text, newDir, len(newDir), "module", proc); err != nil {	14✔
174	return err	×
175	}	×
176
177	return nil	14✔
178	}
179
180	func renderList[T interface {
181	Named
182	Kinded
183	}](list []T, dir []string, proc *Processor) error {	84✔
184	for _, elem := range list {	116✔
185	newDir := appendNew(dir, elem.GetFileName())	32✔
186	text, err := renderElement(elem, proc)	32✔
187	if err != nil {	32✔
188	return err	×
189	}	×
190	if err := linkAndWrite(text, newDir, len(dir), elem.GetKind(), proc); err != nil {	32✔
191	return err	×
192	}	×
193	}
194	return nil	84✔
195	}
196
197	func linkAndWrite(text string, dir []string, modElems int, kind string, proc *Processor) error {	60✔
198	text, err := proc.ReplacePlaceholders(text, dir[1:], modElems-1)	60✔
199	if err != nil {	60✔
200	return err	×
201	}	×
202	outFile := proc.Formatter.ToFilePath(path.Join(dir...), kind)	60✔
203	return proc.writeFile(outFile, text)	60✔
204	}
205
206	func reportMissing(pkg string, missing []missingDocs, stats missingStats, strict bool) error {	4✔
207	if len(missing) == 0 {	4✔
208	fmt.Printf("Docstring coverage of package %s: 100%%\n", pkg)	×
209	return nil	×
210	}	×
211	for _, m := range missing {	56✔
212	fmt.Printf("WARNING: missing %s in %s\n", m.What, m.Who)	52✔
213	}	52✔
214	fmt.Printf("Docstring coverage package %s: %.1f%%\n", pkg, 100.0*float64(stats.Total-stats.Missing)/float64(stats.Total))	4✔
215	if strict {	4✔
216	return fmt.Errorf("missing docstrings in strict mode")	×
217	}	×
218	return nil	4✔
219	}

mlange-42 / modo / 14250580349

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous