Godoc improvements

TykTechnologies · Dec 16, 2024 · 6edb7e2 · 6edb7e2
1 parent f4a589d
commit 6edb7e2
Show file tree

Hide file tree

Showing 11 changed files with 89 additions and 10 deletions.
diff --git a/cmd/go-fsck/example/doc.go b/cmd/go-fsck/example/doc.go
@@ -0,0 +1,2 @@
+// Example package doc.
+package example
diff --git a/cmd/go-fsck/example/go-fsck.json b/cmd/go-fsck/example/go-fsck.json
@@ -4,7 +4,7 @@
     "ImportPath": "github.com/TykTechnologies/exp/cmd/go-fsck/example",
     "Path": ".",
     "TestPackage": false,
-    "Doc": null,
+    "Doc": "Example package doc.",
     "Imports": {
       "example.go": [
         "\"net/http\""
@@ -70,6 +70,7 @@
         "Kind": "func",
         "File": "example.go",
         "SelfContained": false,
+        "Doc": "Global func comment",
         "Name": "GlobalFunc",
         "Returns": [
           "error"
@@ -140,7 +141,7 @@
     "ImportPath": "github.com/TykTechnologies/exp/cmd/go-fsck/example_test",
     "Path": ".",
     "TestPackage": false,
-    "Doc": null,
+    "Doc": "Example package doc.",
     "Imports": {
       "example.go": [
         "\"net/http\""
@@ -206,6 +207,7 @@
         "Kind": "func",
         "File": "example.go",
         "SelfContained": false,
+        "Doc": "Global func comment",
         "Name": "GlobalFunc",
         "Returns": [
           "error"

diff --git a/cmd/go-fsck/extract/extract.go b/cmd/go-fsck/extract/extract.go
@@ -51,6 +51,12 @@ func getDefinitions(cfg *options) ([]*model.Definition, error) {
 		}
 	}
 
+	if !cfg.includeTests {
+		for _, def := range defs {
+			def.ClearTestFiles()
+		}
+	}
+
 	return defs, nil
 }
 

diff --git a/cmd/go-fsck/internal/collector/collector.go b/cmd/go-fsck/internal/collector/collector.go
@@ -170,7 +170,7 @@ func (v *collector) Visit(node ast.Node, push bool, stack []ast.Node) bool {
 	}
 
 	if file.Doc != nil {
-		pkg.Doc.Add(filename, v.getSource(file, file.Doc.List))
+		pkg.Doc = strings.TrimSpace(v.getSource(file, file.Doc))
 	}
 
 	switch node := node.(type) {
@@ -285,6 +285,7 @@ func (v *collector) collectFuncDeclaration(file *ast.File, decl *ast.FuncDecl, f
 	args, returns := v.functionBindings(decl)
 
 	declaration := &Declaration{
+		Doc:        strings.TrimSpace(v.getSource(file, decl.Doc)),
 		Kind:       model.FuncKind,
 		File:       filepath.Base(filename),
 		Name:       decl.Name.Name,
@@ -303,9 +304,14 @@ func (v *collector) collectFuncDeclaration(file *ast.File, decl *ast.FuncDecl, f
 }
 
 func (p *collector) getSource(file *ast.File, node any) string {
+	if commentGroup, ok := node.(*ast.CommentGroup); ok {
+		return commentGroup.Text()
+	}
+
 	var buf strings.Builder
 	err := PrintSource(&buf, p.fset, CommentedNode(file, node))
 	if err != nil {
+		fmt.Printf("Error printing source: %v\n", err)
 		return ""
 	}
 	return buf.String()

diff --git a/cmd/go-fsck/model/declaration.go b/cmd/go-fsck/model/declaration.go
@@ -14,6 +14,8 @@ type Declaration struct {
 
 	References map[string][]string `json:",omitempty"`
 
+	Doc string `json:",omitempty"`
+
 	Name     string   `json:",omitempty"`
 	Names    []string `json:",omitempty"`
 	Receiver string   `json:",omitempty"`

diff --git a/cmd/go-fsck/model/declaration_list.go b/cmd/go-fsck/model/declaration_list.go
@@ -3,6 +3,7 @@ package model
 import (
 	"go/ast"
 	"sort"
+	"strings"
 )
 
 type DeclarationList []*Declaration
@@ -43,6 +44,17 @@ func (p *DeclarationList) ClearSource() {
 	}
 }
 
+func (p *DeclarationList) ClearTestFiles() {
+	result := DeclarationList{}
+	for _, decl := range *p {
+		if strings.HasSuffix(decl.File, "_test.go") {
+			continue
+		}
+		result.Append(decl)
+	}
+	*p = result
+}
+
 func (p *DeclarationList) Sort() {
 	sort.Slice(*p, func(i, j int) bool {
 		a, b := (*p)[i], (*p)[j]

diff --git a/cmd/go-fsck/model/definition.go b/cmd/go-fsck/model/definition.go
@@ -1,9 +1,12 @@
 package model
 
+import "strings"
+
 type Definition struct {
 	Package
 
-	Doc     StringSet
+	Doc string
+
 	Imports StringSet
 	Types   DeclarationList
 	Consts  DeclarationList
@@ -37,6 +40,18 @@ func (d *Definition) ClearSource() {
 	d.Funcs.ClearSource()
 }
 
+func (d *Definition) ClearTestFiles() {
+	for filename, _ := range d.Imports {
+		if strings.HasSuffix(filename, "_test.go") {
+			delete(d.Imports, filename)
+		}
+	}
+	d.Types.ClearTestFiles()
+	d.Vars.ClearTestFiles()
+	d.Consts.ClearTestFiles()
+	d.Funcs.ClearTestFiles()
+}
+
 func (d *Definition) Fill() {
 	for _, decl := range d.Order() {
 		decl.Imports = d.getImports(decl)

diff --git a/cmd/go-fsck/model/restored/declaration.go b/cmd/go-fsck/model/restored/declaration.go
@@ -14,6 +14,8 @@ type Declaration struct {
 
 	References map[string][]string `json:",omitempty"`
 
+	Doc string `json:",omitempty"`
+
 	Name     string   `json:",omitempty"`
 	Names    []string `json:",omitempty"`
 	Receiver string   `json:",omitempty"`

diff --git a/cmd/go-fsck/model/restored/declaration_list.go b/cmd/go-fsck/model/restored/declaration_list.go
@@ -3,6 +3,7 @@ package model
 import (
 	"go/ast"
 	"sort"
+	"strings"
 )
 
 type DeclarationList []*Declaration
@@ -34,6 +35,17 @@ func (p *DeclarationList) ClearSource() {
 	}
 }
 
+func (p *DeclarationList) ClearTestFiles() {
+	result := DeclarationList{}
+	for _, decl := range *p {
+		if strings.HasSuffix(decl.File, "_test.go") {
+			continue
+		}
+		result.Append(decl)
+	}
+	*p = result
+}
+
 func (p *DeclarationList) Sort() {
 	sort.Slice(*p, func(i, j int) bool {
 		a, b := (*p)[i], (*p)[j]

diff --git a/cmd/go-fsck/model/restored/definition.go b/cmd/go-fsck/model/restored/definition.go
@@ -3,7 +3,8 @@ package model
 type Definition struct {
 	Package
 
-	Doc     StringSet
+	Doc string
+
 	Imports StringSet
 	Types   DeclarationList
 	Consts  DeclarationList

diff --git a/cmd/go-fsck/model/restored/go-fsck.json b/cmd/go-fsck/model/restored/go-fsck.json
@@ -4,14 +4,18 @@
     "ImportPath": "github.com/TykTechnologies/exp/cmd/go-fsck/model",
     "Path": ".",
     "TestPackage": false,
-    "Doc": null,
+    "Doc": "",
     "Imports": {
       "declaration.go": [
         "\"strings\""
       ],
       "declaration_list.go": [
         "\"go/ast\"",
-        "\"sort\""
+        "\"sort\"",
+        "\"strings\""
+      ],
+      "definition.go": [
+        "\"strings\""
       ],
       "package.go": [
         "\"fmt\""
@@ -30,7 +34,7 @@
         "File": "declaration.go",
         "SelfContained": true,
         "Name": "Declaration",
-        "Source": "type Declaration struct {\n\tKind\tDeclarationKind\n\tFile\tstring\n\n\tSelfContained\tbool\n\n\tImports\t[]string\t`json:\",omitempty\"`\n\n\tReferences\tmap[string][]string\t`json:\",omitempty\"`\n\n\tName\t\tstring\t\t`json:\",omitempty\"`\n\tNames\t\t[]string\t`json:\",omitempty\"`\n\tReceiver\tstring\t\t`json:\",omitempty\"`\n\n\tArguments\t[]string\t`json:\",omitempty\"`\n\tReturns\t\t[]string\t`json:\",omitempty\"`\n\n\tSignature\tstring\t`json:\",omitempty\"`\n\tSource\t\tstring\t`json:\",omitempty\"`\n}"
+        "Source": "type Declaration struct {\n\tKind\tDeclarationKind\n\tFile\tstring\n\n\tSelfContained\tbool\n\n\tImports\t[]string\t`json:\",omitempty\"`\n\n\tReferences\tmap[string][]string\t`json:\",omitempty\"`\n\n\tDoc\tstring\t`json:\",omitempty\"`\n\n\tName\t\tstring\t\t`json:\",omitempty\"`\n\tNames\t\t[]string\t`json:\",omitempty\"`\n\tReceiver\tstring\t\t`json:\",omitempty\"`\n\n\tArguments\t[]string\t`json:\",omitempty\"`\n\tReturns\t\t[]string\t`json:\",omitempty\"`\n\n\tSignature\tstring\t`json:\",omitempty\"`\n\tSource\t\tstring\t`json:\",omitempty\"`\n}"
       },
       {
         "Kind": "type",
@@ -51,7 +55,7 @@
         "File": "definition.go",
         "SelfContained": true,
         "Name": "Definition",
-        "Source": "type Definition struct {\n\tPackage\n\n\tDoc\tStringSet\n\tImports\tStringSet\n\tTypes\tDeclarationList\n\tConsts\tDeclarationList\n\tVars\tDeclarationList\n\tFuncs\tDeclarationList\n}"
+        "Source": "type Definition struct {\n\tPackage\n\n\tDoc\tstring\n\n\tImports\tStringSet\n\tTypes\tDeclarationList\n\tConsts\tDeclarationList\n\tVars\tDeclarationList\n\tFuncs\tDeclarationList\n}"
       },
       {
         "Kind": "type",
@@ -85,7 +89,7 @@
         "Source": "const (\n\tStructKind\tDeclarationKind\t= \"struct\"\n\tImportKind\t\t\t= \"import\"\n\tConstKind\t\t\t= \"const\"\n\tTypeKind\t\t\t= \"type\"\n\tFuncKind\t\t\t= \"func\"\n\tVarKind\t\t\t\t= \"var\"\n\tCommentKind\t\t\t= \"comment\"\n)"
       }
     ],
-    "Vars": null,
+    "Vars": [],
     "Funcs": [
       {
         "Kind": "func",
@@ -152,6 +156,20 @@
         "Signature": "ClearSource ()",
         "Source": "func (p *DeclarationList) ClearSource() {\n\tfor _, decl := range *p {\n\t\tdecl.Source = \"\"\n\t}\n}"
       },
+      {
+        "Kind": "func",
+        "File": "declaration_list.go",
+        "SelfContained": false,
+        "References": {
+          "strings": [
+            "HasSuffix"
+          ]
+        },
+        "Name": "ClearTestFiles",
+        "Receiver": "*DeclarationList",
+        "Signature": "ClearTestFiles ()",
+        "Source": "func (p *DeclarationList) ClearTestFiles() {\n\tresult := DeclarationList{}\n\tfor _, decl := range *p {\n\t\tif strings.HasSuffix(decl.File, \"_test.go\") {\n\t\t\tcontinue\n\t\t}\n\t\tresult.Append(decl)\n\t}\n\t*p = result\n}"
+      },
       {
         "Kind": "func",
         "File": "declaration_list.go",
@@ -311,6 +329,7 @@
             "HasSuffix"
           ]
         },
+        "Doc": "Map returns a map with the short package name as the key\nand the full import path as the value.",
         "Name": "Map",
         "Receiver": "StringSet",
         "Returns": [