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

2 files changed, 51 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}}{{/*
 
 ---------------------------------------
diff --git a/src/cmd/godoc/godoc.go b/src/cmd/godoc/godoc.go
index ea1dd74cc9..7ca4f83e0a 100644
--- a/src/cmd/godoc/godoc.go
+++ b/src/cmd/godoc/godoc.go
@@ -65,6 +65,7 @@ var (
 	showTimestamps = flag.Bool("timestamps", false, "show timestamps with directory listings")
 	templateDir    = flag.String("templates", "", "directory containing alternate template files")
 	showPlayground = flag.Bool("play", false, "enable playground in web interface")
+	showExamples   = flag.Bool("ex", false, "show examples in command line mode")
 
 	// search index
 	indexEnabled = flag.Bool("index", false, "enable search index")
@@ -329,6 +330,47 @@ func stripExampleSuffix(name string) string {
 	return name
 }
 
+func example_textFunc(funcName string, examples []*doc.Example, fset *token.FileSet, indent string) string {
+	if !*showExamples {
+		return ""
+	}
+
+	var buf bytes.Buffer
+	first := true
+	for _, eg := range examples {
+		name := stripExampleSuffix(eg.Name)
+		if name != funcName {
+			continue
+		}
+
+		if !first {
+			buf.WriteString("\n")
+		}
+		first = false
+
+		// print code
+		cnode := &printer.CommentedNode{Node: eg.Code, Comments: eg.Comments}
+		var buf1 bytes.Buffer
+		writeNode(&buf1, fset, cnode)
+		code := buf1.String()
+		// Additional formatting if this is a function body.
+		if n := len(code); n >= 2 && code[0] == '{' && code[n-1] == '}' {
+			// remove surrounding braces
+			code = code[1 : n-1]
+			// unindent
+			code = strings.Replace(code, "\n    ", "\n", -1)
+		}
+		code = strings.Trim(code, "\n")
+		code = strings.Replace(code, "\n", "\n\t", -1)
+
+		buf.WriteString(indent)
+		buf.WriteString("Example:\n\t")
+		buf.WriteString(code)
+		buf.WriteString("\n")
+	}
+	return buf.String()
+}
+
 func example_htmlFunc(funcName string, examples []*doc.Example, fset *token.FileSet) string {
 	var buf bytes.Buffer
 	for _, eg := range examples {
@@ -494,6 +536,7 @@ var fmap = template.FuncMap{
 
 	// formatting of Examples
 	"example_html":   example_htmlFunc,
+	"example_text":   example_textFunc,
 	"example_name":   example_nameFunc,
 	"example_suffix": example_suffixFunc,
 }