cmd/doc: add option to output a clean one-line symbol representation

gertcuykens · andybons · commit fa42157d986c · 2019-09-19T01:55:12.000Z
Currently there is no way for go doc to output a clean one-line symbol representation of types, functions, vars and consts without documentation lines or other text lines added. For example `go doc fmt` has a huge introduction so if you pass that to grep or fzf to search a symbol let say scan `go doc fmt | grep scan` you get way to many false positives. Added a `-short` flag to be able to do `go doc -short fmt | grep scan` instead which will result in just the symbols you are looking for. func Fscan(r io.Reader, a ...interface{}) (n int, err error) func Fscanf(r io.Reader, format string, a ...interface{}) (n int, err error) func Fscanln(r io.Reader, a ...interface{}) (n int, err error) func Sscan(str string, a ...interface{}) (n int, err error) func Sscanf(str string, format string, a ...interface{}) (n int, err error) func Sscanln(str string, a ...interface{}) (n int, err error) Fixes golang#32597 Change-Id: I77a73838adc512c8d1490f5a82075de6b0462a31 Reviewed-on: https://go-review.googlesource.com/c/go/+/184017 Run-TryBot: Andrew Bonventre <andybons@golang.org> TryBot-Result: Gobot Gobot <gobot@golang.org> Reviewed-by: Andrew Bonventre <andybons@golang.org>
diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go
@@ -210,6 +210,18 @@ var tests = []test{
 			`func \(unexportedType\)`,
 		},
 	},
+	// Package dump -short
+	{
+		"full package with -short",
+		[]string{`-short`, p},
+		[]string{
+			`const ExportedConstant = 1`,               // Simple constant.
+			`func ReturnUnexported\(\) unexportedType`, // Function with unexported return type.
+		},
+		[]string{
+			`MultiLine(String|Method|Field)`, // No data from multi line portions.
+		},
+	},
 	// Package dump -u
 	{
 		"full package with u",
diff --git a/src/cmd/doc/main.go b/src/cmd/doc/main.go
@@ -57,6 +57,7 @@ var (
 	showAll    bool // -all flag
 	showCmd    bool // -cmd flag
 	showSrc    bool // -src flag
+	short      bool // -short flag
 )
 
 // usage is a replacement usage function for the flags package.
@@ -94,6 +95,7 @@ func do(writer io.Writer, flagSet *flag.FlagSet, args []string) (err error) {
 	flagSet.BoolVar(&showAll, "all", false, "show all documentation for package")
 	flagSet.BoolVar(&showCmd, "cmd", false, "show symbols with package docs even if package is a command")
 	flagSet.BoolVar(&showSrc, "src", false, "show source code for symbol")
+	flagSet.BoolVar(&short, "short", false, "one-line representation for each symbol")
 	flagSet.Parse(args)
 	var paths []string
 	var symbol, method string
diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
@@ -507,24 +507,34 @@ func (pkg *Package) allDoc() {
 func (pkg *Package) packageDoc() {
 	defer pkg.flush()
 
-	doc.ToText(&pkg.buf, pkg.doc.Doc, "", indent, indentedWidth)
-	pkg.newlines(1)
+	if !short {
+		doc.ToText(&pkg.buf, pkg.doc.Doc, "", indent, indentedWidth)
+		pkg.newlines(1)
+	}
 
 	if pkg.pkg.Name == "main" && !showCmd {
 		// Show only package docs for commands.
 		return
 	}
 
-	pkg.newlines(2) // Guarantee blank line before the components.
+	if !short {
+		pkg.newlines(2) // Guarantee blank line before the components.
+	}
+
 	pkg.valueSummary(pkg.doc.Consts, false)
 	pkg.valueSummary(pkg.doc.Vars, false)
 	pkg.funcSummary(pkg.doc.Funcs, false)
 	pkg.typeSummary()
-	pkg.bugs()
+	if !short {
+		pkg.bugs()
+	}
 }
 
 // packageClause prints the package clause.
 func (pkg *Package) packageClause() {
+	if short {
+		return
+	}
 	importPath := pkg.build.ImportComment
 	if importPath == "" {
 		importPath = pkg.build.ImportPath
diff --git a/src/cmd/go/alldocs.go b/src/cmd/go/alldocs.go
diff --git a/src/cmd/go/internal/doc/doc.go b/src/cmd/go/internal/doc/doc.go
@@ -114,6 +114,8 @@ Flags:
 		Treat a command (package main) like a regular package.
 		Otherwise package main's exported symbols are hidden
 		when showing the package's top-level documentation.
+	-short
+		One-line representation for each symbol.
 	-src
 		Show the full source code for the symbol. This will
 		display the full Go source of its declaration and
