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>

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",

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

src/cmd/doc/pkg.go

@@ -507,24 +507,34 @@ func (pkg *Package) allDoc() {
 func (pkg *Package) packageDoc() {
 	defer pkg.flush()
 
+	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
 	}
 
+	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()
+	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

src/cmd/go/alldocs.go

@@ -363,6 +363,8 @@
 // 		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

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