cmd/doc: group constructors with type in package presentation

Fixes #14004.

$ go doc encoding.gob
Before:
func Register(value interface{})
func RegisterName(name string, value interface{})
func NewDecoder(r io.Reader) *Decoder
func NewEncoder(w io.Writer) *Encoder
type CommonType struct { ... }
type Decoder struct { ... }
type Encoder struct { ... }
type GobDecoder interface { ... }
type GobEncoder interface { ... }

After:
func Register(value interface{})
func RegisterName(name string, value interface{})
type CommonType struct { ... }
type Decoder struct { ... }
    func NewDecoder(r io.Reader) *Decoder
type Encoder struct { ... }
    func NewEncoder(w io.Writer) *Encoder
type GobDecoder interface { ... }
type GobEncoder interface { ... }

Change-Id: I021db25bce4a16b3dfa22ab323ca1f4e68d50111
Reviewed-on: https://go-review.googlesource.com/22354
Reviewed-by: Robert Griesemer <gri@golang.org>

diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
index d0983d447d5dd1c6964d818199fc489b4addfb25..efd681d5149f92cdfe09977965fbafbff80e157d 100644 (file)
--- a/src/cmd/doc/pkg.go
+++ b/src/cmd/doc/pkg.go
@@ -268,7 +268,7 @@ func (pkg *Package) packageDoc() {
        pkg.newlines(2) // Guarantee blank line before the components.
        pkg.valueSummary(pkg.doc.Consts)
        pkg.valueSummary(pkg.doc.Vars)
-       pkg.funcSummary(pkg.doc.Funcs)
+       pkg.funcSummary(pkg.doc.Funcs, false)
        pkg.typeSummary()
        pkg.bugs()
 }
@@ -308,24 +308,44 @@ func (pkg *Package) valueSummary(values []*doc.Value) {
        }
 }
 
-// funcSummary prints a one-line summary for each function.
-func (pkg *Package) funcSummary(funcs []*doc.Func) {
+// funcSummary prints a one-line summary for each function. Constructors
+// are printed by typeSummary, below, and so can be suppressed here.
+func (pkg *Package) funcSummary(funcs []*doc.Func, showConstructors bool) {
+       // First, identify the constructors. Don't bother figuring out if they're exported.
+       var isConstructor map[*doc.Func]bool
+       if !showConstructors {
+               isConstructor = make(map[*doc.Func]bool)
+               for _, typ := range pkg.doc.Types {
+                       for _, constructor := range typ.Funcs {
+                               isConstructor[constructor] = true
+                       }
+               }
+       }
        for _, fun := range funcs {
                decl := fun.Decl
                // Exported functions only. The go/doc package does not include methods here.
                if isExported(fun.Name) {
-                       pkg.oneLineFunc(decl)
+                       if !isConstructor[fun] {
+                               pkg.oneLineFunc(decl)
+                       }
                }
        }
 }
 
-// typeSummary prints a one-line summary for each type.
+// typeSummary prints a one-line summary for each type, followed by its constructors.
 func (pkg *Package) typeSummary() {
        for _, typ := range pkg.doc.Types {
                for _, spec := range typ.Decl.Specs {
                        typeSpec := spec.(*ast.TypeSpec) // Must succeed.
                        if isExported(typeSpec.Name.Name) {
                                pkg.oneLineTypeDecl(typeSpec)
+                               // Now print the constructors.
+                               for _, constructor := range typ.Funcs {
+                                       if isExported(constructor.Name) {
+                                               pkg.Printf(indent)
+                                               pkg.oneLineFunc(constructor.Decl)
+                                       }
+                               }
                        }
                }
        }
@@ -453,8 +473,8 @@ func (pkg *Package) symbolDoc(symbol string) bool {
                }
                pkg.valueSummary(typ.Consts)
                pkg.valueSummary(typ.Vars)
-               pkg.funcSummary(typ.Funcs)
-               pkg.funcSummary(typ.Methods)
+               pkg.funcSummary(typ.Funcs, true)
+               pkg.funcSummary(typ.Methods, true)
                found = true
        }
        if !found {