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>

diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go
index 11d0bdafd9943277cf9972dbbd780a77fa6441b2..7bc5842cc6a48c07f6793434401ab1dff9f0e1d2 100644 (file)
--- 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 a739761afe34e7217a05d5fdf0f06aafe4496c77..dd15e801fb9e3ac97b134ee919e81d8c68a70a08 100644 (file)
--- 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 2c0c6c161ae1dd8fd9a196d68d8290d1ec7b63fa..fa31eba64bb29379f24b8d282282a2e3e858b8a1 100644 (file)
--- 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
index 36fa528a9012b2d4291877ac787b3cfd8f1f15bc..847a7c5020ba014533a82b673f99ba8ddbd1ac3b 100644 (file)
--- a/src/cmd/go/alldocs.go
+++ b/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

diff --git a/src/cmd/go/internal/doc/doc.go b/src/cmd/go/internal/doc/doc.go
index bad05ff9128cb523fa6553b353b7117fab81ab9c..4ff08bb9289a09bee8e84dd31cdbe69a987e567b 100644 (file)
--- 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