[pkgsite] devtools/cmd/evaldoc: tool for doc coverage

0 views

Skip to first unread message

Jonathan Amsterdam (Gerrit)

unread,

Aug 6, 2026, 1:13:23 PM (4 days ago) Aug 6

to goph...@pubsubhelper.golang.org, golang-...@googlegroups.com, kokoro, golang...@luci-project-accounts.iam.gserviceaccount.com, Ethan Lee, Hyang-Ah Hana Kim, golang-co...@googlegroups.com

Jonathan Amsterdam submitted the change with unreviewed changes

Unreviewed changes

1 is the latest approved patch-set.
The change was submitted with unreviewed changes in the following files:

```
The name of the file: devtools/cmd/evaldoc/main.go
Insertions: 11, Deletions: 3.

@@ -4,6 +4,11 @@
 
 // The evaldoc command takes a local directory path, loads the module,
 // and prints symbols and whether they have documentation to standard output.
+//
+// It can be used to better understand the "documentation coverage" score
+// on a package's evaluations page (pkg.go.dev/IMPORT/PATH?tab=evals).
+// Run it on your module to get a list of symbols which need documentation,
+// and whether they have documentation.
 package main
 
 import (
@@ -51,9 +56,9 @@
 // the absolute path of arg.
 func resolveLocalPath(arg string) (string, error) {
 	if strings.HasPrefix(arg, "~") {
-		home := os.Getenv("HOME")
-		if home == "" {
-			return "", errors.New("$HOME is not set")
+		home, err := os.UserHomeDir()
+		if err != nil {
+			return "", fmt.Errorf("arg is local path, but cannot get home directory: %v", err)
 		}
 		arg = filepath.Join(home, arg[1:])
 	}
@@ -145,11 +150,14 @@
 			fp := path.Join(relDir, fname)
 			content, err := fs.ReadFile(contentDir, fp)
 			if err != nil {
+				fmt.Fprintf(os.Stderr, "%s: reading: %v", fp, err)
 				continue
 			}
 			f, err := parser.ParseFile(fset, fname, content, parser.ParseComments)
 			if err == nil {
 				astFiles = append(astFiles, f)
+			} else {
+				fmt.Fprintf(os.Stderr, "%s: parsing: %v", fp, err)
 			}
 		}
 
```

Change information

Commit message:

devtools/cmd/evaldoc: tool for doc coverage

This is the first of several CLs that implement a tool for
documentation coverage. Users can run this to better understand their
documentation coverage score on the evaluations page.

This first CL has limited functionality: it reads only from the file
system, and just writes a simple list of symbols and whether they are
documented. Over the next few CLs, we'll build on that to produce a web
server that shows the symbols in context.

As part of this change, we modify CollectSymbols to use the Go
identifier instead of a name for the symbol. That means we lose some
context information, like the type that a method is defined on. This
isn't going to matter for this program, because we will be showing the
name in context. And it doesn't matter for production use because there
we only count the number of symbols.

For golang/go#80385.

Change-Id: I62c84e953719c5a3f347334669b3d71b7dd10e59

Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/811060

LUCI-TryBot-Result: golang...@luci-project-accounts.iam.gserviceaccount.com <golang...@luci-project-accounts.iam.gserviceaccount.com>

Reviewed-by: Ethan Lee <etha...@google.com>

kokoro-CI: kokoro <noreply...@google.com>

Files:

A devtools/cmd/evaldoc/main.go
M internal/frontend/evals.go
M internal/frontend/evals_test.go

Change size: L

Delta: 3 files changed, 217 insertions(+), 41 deletions(-)

Branch: refs/heads/master

Submit Requirements:

Code-Review: +2 by Ethan Lee
TryBots-Pass: LUCI-TryBot-Result+1 by golang...@luci-project-accounts.iam.gserviceaccount.com
kokoro-CI-Passes: kokoro-CI+1 by kokoro

Open in Gerrit

Inspect html for hidden footers to help with email filtering. To unsubscribe visit settings.

Gerrit

open

diffy

satisfied_requirement

Reply all

Reply to author

Forward

0 new messages