1
0
mirror of https://github.com/golang/go synced 2024-11-12 01:20:22 -07:00

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
This commit is contained in:
Volker Dobler 2013-02-25 10:37:17 +11:00 committed by Andrew Gerrand
parent 1174a18c3d
commit d97b975d5c
2 changed files with 51 additions and 3 deletions

View File

@ -9,7 +9,8 @@ package {{.Name}}
{{else}}COMMAND DOCUMENTATION {{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}} {{range .}}{{node .Decl $.FSet}}
{{comment_text .Doc " " "\t"}} {{comment_text .Doc " " "\t"}}
{{example_text .Name $.Examples $.FSet " "}}
{{end}}{{end}}{{/* {{end}}{{end}}{{/*
--------------------------------------- ---------------------------------------
@ -43,16 +45,19 @@ FUNCTIONS
*/}}{{with .Types}} */}}{{with .Types}}
TYPES TYPES
{{range .}}{{node .Decl $.FSet}} {{range .}}{{$tname := .Name}}{{node .Decl $.FSet}}
{{comment_text .Doc " " "\t"}} {{comment_text .Doc " " "\t"}}
{{range .Consts}}{{node .Decl $.FSet}} {{range .Consts}}{{node .Decl $.FSet}}
{{comment_text .Doc " " "\t"}} {{comment_text .Doc " " "\t"}}
{{end}}{{range .Vars}}{{node .Decl $.FSet}} {{end}}{{range .Vars}}{{node .Decl $.FSet}}
{{comment_text .Doc " " "\t"}} {{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"}} {{comment_text .Doc " " "\t"}}
{{example_text .Name $.Examples $.FSet " "}}
{{end}}{{range .Methods}}{{node .Decl $.FSet}} {{end}}{{range .Methods}}{{node .Decl $.FSet}}
{{comment_text .Doc " " "\t"}} {{comment_text .Doc " " "\t"}}
{{$name := printf "%s_%s" $tname .Name}}{{example_text $name $.Examples $.FSet " "}}
{{end}}{{end}}{{end}}{{/* {{end}}{{end}}{{end}}{{/*
--------------------------------------- ---------------------------------------

View File

@ -65,6 +65,7 @@ var (
showTimestamps = flag.Bool("timestamps", false, "show timestamps with directory listings") showTimestamps = flag.Bool("timestamps", false, "show timestamps with directory listings")
templateDir = flag.String("templates", "", "directory containing alternate template files") templateDir = flag.String("templates", "", "directory containing alternate template files")
showPlayground = flag.Bool("play", false, "enable playground in web interface") showPlayground = flag.Bool("play", false, "enable playground in web interface")
showExamples = flag.Bool("ex", false, "show examples in command line mode")
// search index // search index
indexEnabled = flag.Bool("index", false, "enable search index") indexEnabled = flag.Bool("index", false, "enable search index")
@ -329,6 +330,47 @@ func stripExampleSuffix(name string) string {
return name 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 { func example_htmlFunc(funcName string, examples []*doc.Example, fset *token.FileSet) string {
var buf bytes.Buffer var buf bytes.Buffer
for _, eg := range examples { for _, eg := range examples {
@ -494,6 +536,7 @@ var fmap = template.FuncMap{
// formatting of Examples // formatting of Examples
"example_html": example_htmlFunc, "example_html": example_htmlFunc,
"example_text": example_textFunc,
"example_name": example_nameFunc, "example_name": example_nameFunc,
"example_suffix": example_suffixFunc, "example_suffix": example_suffixFunc,
} }