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

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 #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>

3 files changed, 28 insertions, 4 deletions

diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go
index 11d0bdafd9..7bc5842cc6 100644
--- 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
index a739761afe..dd15e801fb 100644
--- 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
index 2c0c6c161a..fa31eba64b 100644
--- 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