cmd/godoc: show examples in text mode

Added the command line flag -ex to godoc to print examples in
text output.

Samples from the generated output:

$ godoc -ex strings Index
...
func Index(s, sep string) int
    Index returns the index of the first instance of sep in s, or -1 if sep
    is not present in s.

    Example:
        fmt.Println(strings.Index("chicken", "ken"))
        fmt.Println(strings.Index("chicken", "dmr"))
        // Output:
        // 4
        // -1
...

$ godoc -ex container/heap
...
package heap
    import "container/heap"

    Package heap provides heap operations for any type that implements
    heap.Interface. A heap is a tree with the property that each node is the
    minimum-valued node in its subtree.

    Example:
        // This example demonstrates an integer heap built using the heap interface.
        package heap_test

        import (
            "container/heap"
            "fmt"
        ...

    Example:
        // This example demonstrates a priority queue built using the heap interface.
        package heap_test

        import (
            "container/heap"
            "fmt"
        )
...

Fixes #3587.

R=golang-dev, minux.ma, adg, rsc, gri
CC=golang-dev
https://golang.org/cl/7356043

1 files changed, 8 insertions, 3 deletions

diff --git a/lib/godoc/package.txt b/lib/godoc/package.txt
index 16678d5f01..ab9506d65a 100644
--- a/lib/godoc/package.txt
+++ b/lib/godoc/package.txt
@@ -9,7 +9,8 @@ package {{.Name}}
 
 {{else}}COMMAND DOCUMENTATION
 
-{{end}}{{comment_text .Doc "    " "\t"}}{{/*
+{{end}}{{comment_text .Doc "    " "\t"}}
+{{example_text "" $.Examples $.FSet "    "}}{{/*
 
 ---------------------------------------
 
@@ -36,6 +37,7 @@ FUNCTIONS
 
 {{range .}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
+{{example_text .Name $.Examples $.FSet "    "}}
 {{end}}{{end}}{{/*
 
 ---------------------------------------
@@ -43,16 +45,19 @@ FUNCTIONS
 */}}{{with .Types}}
 TYPES
 
-{{range .}}{{node .Decl $.FSet}}
+{{range .}}{{$tname := .Name}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
 {{range .Consts}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
 {{end}}{{range .Vars}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
-{{end}}{{range .Funcs}}{{node .Decl $.FSet}}
+{{end}}{{example_text .Name $.Examples $.FSet "    "}}
+{{range .Funcs}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
+{{example_text .Name $.Examples $.FSet "    "}}
 {{end}}{{range .Methods}}{{node .Decl $.FSet}}
 {{comment_text .Doc "    " "\t"}}
+{{$name := printf "%s_%s" $tname .Name}}{{example_text $name $.Examples $.FSet "    "}}
 {{end}}{{end}}{{end}}{{/*
 
 ---------------------------------------