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

diff --git a/lib/godoc/package.txt b/lib/godoc/package.txt
index 16678d5f01a0a4735fa9c14e8941f52499a1dbbc..ab9506d65af01a6142938176ad1284d222231e21 100644 (file)
--- 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 ea1dd74cc90778f9e47141081f8feb220ec4d19f..7ca4f83e0a3d537debd6eb7a7cb77731f5eed2a3 100644 (file)
--- 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,
 }