code review 243041: godoc: don't throw away function documentation

src/pkg/go/doc/doc.go

 // Copyright 2009 The Go Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style
 // license that can be found in the LICENSE file.
 
 // The doc package extracts source code documentation from a Go AST.
 package doc
 
 import (
         "container/vector"
         "go/ast"
@@ skipping 129 matching lines @@
                 typ := doc.lookupTypeDoc(domName)
                 if typ != nil {
                         values = typ.values // associate with that type
                 }
         }
 
         values.Push(decl)
 }
 
 
+// Helper function to set the table entry for function f. Makes sure that
+// at least one f with associated documentation is stored in table, if there
+// are multiple f's with the same name.
+func setFunc(table map[string]*ast.FuncDecl, f *ast.FuncDecl) {
+        name := f.Name.Name()
+        if g, exists := table[name]; exists && g.Doc != nil {
+                // a function with the same name has already been registered;
+                // since it has documentation, assume f is simply another
+                // implementation and ignore it
+                // TODO(gri) consider collecting all functions, or at least
+                //           all comments
+                return
+        }
+        // function doesn't exist or has no documentation; use f
+        table[name] = f
+}
+
+
 func (doc *docReader) addFunc(fun *ast.FuncDecl) {
         name := fun.Name.Name()
 
         // determine if it should be associated with a type
         if fun.Recv != nil {
                 // method
                 typ := doc.lookupTypeDoc(baseTypeName(fun.Recv.List[0].Type))
                 if typ != nil {
                         // exported receiver type
-                        typ.methods[name] = fun
+                        setFunc(typ.methods, fun)
                 }
                 // otherwise don't show the method
                 // TODO(gri): There may be exported methods of non-exported types
                 // that can be called because of exported values (consts, vars, or
                 // function results) of that type. Could determine if that is the
                 // case and then show those methods in an appropriate section.
                 return
         }
 
         // perhaps a factory function
@@ skipping 10 matching lines @@
                                 // named and exported result type
 
                                 // Work-around for failure of heuristic: In package os
                                 // too many functions are considered factory functions
                                 // for the Error type. Eliminate manually for now as
                                 // this appears to be the only important case in the
                                 // current library where the heuristic fails.
                                 if doc.pkgName == "os" && tname == "Error" &&
                                         name != "NewError" && name != "NewSyscallError" {
                                         // not a factory function for os.Error
-                                        doc.funcs[name] = fun // treat as ordinary function
+                                        setFunc(doc.funcs, fun) // treat as ordinary function
                                         return
                                 }
 
-                                typ.factories[name] = fun
+                                setFunc(typ.factories, fun)
                                 return
                         }
                 }
         }
 
         // ordinary function
-        doc.funcs[name] = fun
+        setFunc(doc.funcs, fun)
 }
 
 
 func (doc *docReader) addDecl(decl ast.Decl) {
         switch d := decl.(type) {
         case *ast.GenDecl:
                 if len(d.Specs) > 0 {
                         switch d.Tok {
                         case token.CONST, token.VAR:
                                 // constants and variables are always handled as a group
@@ skipping 433 matching lines @@
 // TODO: Recognize "Type.Method" as a name.
 // TODO(r): maybe precompile the regexps.
 //
 func (p *PackageDoc) Filter(names []string) {
         p.Consts = filterValueDocs(p.Consts, names)
         p.Vars = filterValueDocs(p.Vars, names)
         p.Types = filterTypeDocs(p.Types, names)
         p.Funcs = filterFuncDocs(p.Funcs, names)
         p.Doc = "" // don't show top-level package doc
 }