Allow missing self and out arguments (#137)

CHANGELOG.md

@@ -2,7 +2,7 @@
 
 ### Features
 
-* Adds flag/config entry `report-missing` to report missing docstrings and coverage (#136)
+* Adds flag/config entry `report-missing` to report missing docstrings and coverage (#136, #137)
 
 ### Documentation
 

document/doctest.go

@@ -38,6 +38,7 @@ func (proc *Processor) extractDocTestsMarkdown(baseDir string, build bool) error
 		return err
 	}
 	if proc.Config.TestOutput != "" {
+		fmt.Printf("Extracted %d test(s) from Markdown files.\n", len(proc.docTests))
 		err = proc.writeDocTests(proc.Config.TestOutput)
 		if err != nil {
 			return err
@@ -104,7 +105,6 @@ func (proc *Processor) writeDocTests(dir string) error {
 			return err
 		}
 	}
-	fmt.Printf("Extracted %d tests.\n", len(proc.docTests))
 	return nil
 }
 

document/document.go

@@ -35,7 +35,10 @@ type Package struct {
 }
 
 func (p *Package) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
-	newPath := fmt.Sprintf("%s.%s", path, p.Name)
+	newPath := p.Name
+	if len(path) > 0 {
+		newPath = fmt.Sprintf("%s.%s", path, p.Name)
+	}
 	missing = p.MemberSummary.CheckMissing(newPath, stats)
 	for _, e := range p.Packages {
 		missing = append(missing, e.CheckMissing(newPath, stats)...)
@@ -241,6 +244,12 @@ type Arg struct {
 }
 
 func (a *Arg) CheckMissing(path string, stats *missingStats) (missing []missingDocs) {
+	if a.Name == "self" && a.Type == "Self" {
+		return nil
+	}
+	if a.Convention == "out" {
+		return nil
+	}
 	if a.Description == "" {
 		missing = append(missing, missingDocs{fmt.Sprintf("%s.%s", path, a.Name), "description"})
 		stats.Missing++

document/processor.go

@@ -1,6 +1,7 @@
 package document
 
 import (
+	"fmt"
 	"os"
 	"path"
 	"strings"
@@ -84,6 +85,7 @@ func (proc *Processor) ExtractTests(subdir string) error {
 		return err
 	}
 	if proc.Config.TestOutput != "" {
+		fmt.Printf("Extracted %d test(s) from package %s.\n", len(proc.docTests), proc.Docs.Decl.Name)
 		outPath := path.Join(proc.Config.TestOutput, subdir, proc.Docs.Decl.Name)
 		err = proc.writeDocTests(outPath)
 		if err != nil {

document/render.go

@@ -86,13 +86,11 @@ func renderWith(config *Config, proc *Processor, subdir string) error {
 	if err := proc.Formatter.WriteAuxiliary(proc.ExportDocs.Decl, outPath, proc); err != nil {
 		return err
 	}
-
 	if config.ReportMissing {
-		if err := reportMissing(missing, stats, config.Strict); err != nil {
+		if err := reportMissing(proc.Docs.Decl.Name, missing, stats, config.Strict); err != nil {
 			return err
 		}
 	}
-
 	return nil
 }
 
@@ -201,15 +199,15 @@ func linkAndWrite(text string, dir []string, modElems int, kind string, proc *Pr
 	return proc.WriteFile(outFile, text)
 }
 
-func reportMissing(missing []missingDocs, stats missingStats, strict bool) error {
+func reportMissing(pkg string, missing []missingDocs, stats missingStats, strict bool) error {
 	if len(missing) == 0 {
-		fmt.Println("Docstring coverage: 100%")
+		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: %.1f%%\n", 100.0*float64(stats.Total-stats.Missing)/float64(stats.Total))
+	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")
 	}