cmd/doc: print Go syntax when printing struct.field docs

Fixes #20928

Change-Id: I7f7aafb8ff4b5deb50c286a9ae81c34ee85e56a9
Reviewed-on: https://go-review.googlesource.com/47730
Reviewed-by: Rob Pike <r@golang.org>
Run-TryBot: Brad Fitzpatrick <bradfitz@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>

diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go
index e534bfead30454f40545d137e329e3cf417f6d14..89282529983d6d10fc00d9853d8f6532603ee817 100644 (file)
--- a/src/cmd/doc/doc_test.go
+++ b/src/cmd/doc/doc_test.go
@@ -89,7 +89,7 @@ var tests = []test{
                        `VarFive = 5`,                       // From block starting with unexported variable.
                        `type unexportedType`,               // No unexported type.
                        `unexportedTypedConstant`,           // No unexported typed constant.
-                       `Field`,                             // No fields.
+                       `\bField`,                           // No fields.
                        `Method`,                            // No methods.
                        `someArgument[5-8]`,                 // No truncated arguments.
                        `type T1 T2`,                        // Type alias does not display as type declaration.
@@ -395,14 +395,16 @@ var tests = []test{
                "field",
                []string{p, `ExportedType.ExportedField`},
                []string{
+                       `type ExportedType struct`,
                        `ExportedField int`,
                        `Comment before exported field.`,
                        `Comment on line with exported field.`,
+                       `other fields elided`,
                },
                nil,
        },
 
-       // Field  with -u.
+       // Field with -u.
        {
                "method with -u",
                []string{"-u", p, `ExportedType.unexportedField`},
@@ -413,6 +415,14 @@ var tests = []test{
                nil,
        },
 
+       // Field of struct with only one field.
+       {
+               "single-field struct",
+               []string{p, `ExportedStructOneField.OnlyField`},
+               []string{`the only field`},
+               []string{`other fields elided`},
+       },
+
        // Case matching off.
        {
                "case matching off",

diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
index 7b0f9de775a0bd014457b7011c86c0c831bb67ed..5a14d6e7cf5e4b3f767389344433731fe3af37ba 100644 (file)
--- a/src/cmd/doc/pkg.go
+++ b/src/cmd/doc/pkg.go
@@ -833,6 +833,7 @@ func (pkg *Package) printFieldDoc(symbol, fieldName string) bool {
                pkg.Fatalf("symbol %s is not a type in package %s installed in %q", symbol, pkg.name, pkg.build.ImportPath)
        }
        found := false
+       numUnmatched := 0
        for _, typ := range types {
                // Type must be a struct.
                spec := pkg.findTypeSpec(typ.Decl, typ.Name)
@@ -844,27 +845,32 @@ func (pkg *Package) printFieldDoc(symbol, fieldName string) bool {
                for _, field := range structType.Fields.List {
                        // TODO: Anonymous fields.
                        for _, name := range field.Names {
-                               if match(fieldName, name.Name) {
-                                       if !found {
-                                               pkg.Printf("struct %s {\n", typ.Name)
-                                       }
-                                       if field.Doc != nil {
-                                               for _, comment := range field.Doc.List {
-                                                       doc.ToText(&pkg.buf, comment.Text, indent, indent, indentedWidth)
-                                               }
-                                       }
-                                       s := pkg.oneLineNode(field.Type)
-                                       lineComment := ""
-                                       if field.Comment != nil {
-                                               lineComment = fmt.Sprintf("  %s", field.Comment.List[0].Text)
+                               if !match(fieldName, name.Name) {
+                                       numUnmatched++
+                                       continue
+                               }
+                               if !found {
+                                       pkg.Printf("type %s struct {\n", typ.Name)
+                               }
+                               if field.Doc != nil {
+                                       for _, comment := range field.Doc.List {
+                                               doc.ToText(&pkg.buf, comment.Text, indent, indent, indentedWidth)
                                        }
-                                       pkg.Printf("%s%s %s%s\n", indent, name, s, lineComment)
-                                       found = true
                                }
+                               s := pkg.oneLineNode(field.Type)
+                               lineComment := ""
+                               if field.Comment != nil {
+                                       lineComment = fmt.Sprintf("  %s", field.Comment.List[0].Text)
+                               }
+                               pkg.Printf("%s%s %s%s\n", indent, name, s, lineComment)
+                               found = true
                        }
                }
        }
        if found {
+               if numUnmatched > 0 {
+                       pkg.Printf("\n    // ... other fields elided ...\n")
+               }
                pkg.Printf("}\n")
        }
        return found

diff --git a/src/cmd/doc/testdata/pkg.go b/src/cmd/doc/testdata/pkg.go
index 4e08c84233ad3165d40fcfc8f356bb7be4c4ac9f..99755b11c56e571dd64f849a3e9260b2921598c2 100644 (file)
--- a/src/cmd/doc/testdata/pkg.go
+++ b/src/cmd/doc/testdata/pkg.go
@@ -80,6 +80,10 @@ func (ExportedType) unexportedMethod(a int) bool {
        return true
 }
 
+type ExportedStructOneField struct {
+       OnlyField int // the only field
+}
+
 // Constants tied to ExportedType. (The type is a struct so this isn't valid Go,
 // but it parses and that's all we need.)
 const (