|
|
Created:
11 years, 1 month ago by volker.dobler Modified:
11 years, 1 month ago Reviewers:
CC:
golang-dev, minux1, adg, rsc, gri Visibility:
Public. |
Descriptioncmd/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 issue 3587.
Patch Set 1 #Patch Set 2 : diff -r f30bdd45914c https://code.google.com/p/go/ #Patch Set 3 : diff -r f30bdd45914c https://code.google.com/p/go/ #
Total comments: 2
Patch Set 4 : diff -r 28f7394b058f https://code.google.com/p/go/ #Patch Set 5 : diff -r dd18b993ba95 https://code.google.com/p/go/ #Patch Set 6 : diff -r dd18b993ba95 https://code.google.com/p/go/ #
Total comments: 2
Patch Set 7 : diff -r 3b285c00863b https://code.google.com/p/go/ #MessagesTotal messages: 16
Hello golang-dev@googlegroups.com (cc: golang-dev@googlegroups.com), I'd like you to review this change to https://code.google.com/p/go/
Sign in to reply to this message.
As cmd/godoc already supports generating complete example code for its -play features, i'm wondering if we can have a way to make godoc generate a complete Go source file for experimenting with a single example. For example, I think "godoc -ex regexp FindStringIndex" could display this: $ godoc -ex regexp FindStringIndex // type Regexp struct { // // contains filtered or unexported fields // } // Regexp is the representation of a compiled regular expression. The // public interface is entirely through methods. A Regexp is safe for // concurrent use by multiple goroutines. // // func (re *Regexp) FindStringIndex(s string) (loc []int) // FindStringIndex returns a two-element slice of integers defining the // location of the leftmost match in s of the regular expression. The match // itself is at s[loc[0]:loc[1]]. A return value of nil indicates no match. package main import ( "fmt" "regexp" ) // Example Regexp.FindStringIndex func main() { re := regexp.MustCompile("ab?") fmt.Println(re.FindStringIndex("tablett")) fmt.Println(re.FindStringIndex("foo") == nil) // Output: // [1 3] // true }
Sign in to reply to this message.
https://codereview.appspot.com/7356043/diff/3/src/cmd/godoc/godoc.go File src/cmd/godoc/godoc.go (right): https://codereview.appspot.com/7356043/diff/3/src/cmd/godoc/godoc.go#newcode372 src/cmd/godoc/godoc.go:372: header = fmt.Sprintf("\t// ------ Example %s ", example_nameFunc(eg.Name)) can't we just use indentation to delineate the examples, as we do with all other blocks of text or code in the text examples?
Sign in to reply to this message.
That would be doable. One would have to decide what to output in the following cases: * $ godoc -ex strings all examples in one main? * $ godoc -ex os which contains no examples * $ godoc -ex container/heap which contains two full examples * $ gdoc -ex regexp Match no example here Additionally it makes using text mode godoc awkward: Users have to do a '$ godoc strings' first to see which functions are in package strings and in a second step run '$ godoc -ex strings ContainsAny' to see the example if the function's doc was not enlightening enough. On Mon, Feb 18, 2013 at 5:33 PM, minux <minux.ma@gmail.com> wrote: > As cmd/godoc already supports generating complete example code for its > -play > features, i'm wondering if we can have a way to make godoc generate a > complete > Go source file for experimenting with a single example. > > For example, I think "godoc -ex regexp FindStringIndex" could display > this: > > $ godoc -ex regexp FindStringIndex > // type Regexp struct { > // // contains filtered or unexported fields > // } > // Regexp is the representation of a compiled regular expression. The > // public interface is entirely through methods. A Regexp is safe for > // concurrent use by multiple goroutines. > // > // func (re *Regexp) FindStringIndex(s string) (loc []int) > // FindStringIndex returns a two-element slice of integers defining the > // location of the leftmost match in s of the regular expression. The > match > // itself is at s[loc[0]:loc[1]]. A return value of nil indicates no > match. > > package main > > import ( > "fmt" > "regexp" > ) > > // Example Regexp.FindStringIndex > func main() { > re := regexp.MustCompile("ab?") > fmt.Println(re.FindStringIndex("tablett")) > fmt.Println(re.FindStringIndex("foo") == nil) > // Output: > // [1 3] > // true > } > > -- Dr. Volker Dobler
Sign in to reply to this message.
PTAL https://codereview.appspot.com/7356043/diff/3/src/cmd/godoc/godoc.go File src/cmd/godoc/godoc.go (right): https://codereview.appspot.com/7356043/diff/3/src/cmd/godoc/godoc.go#newcode372 src/cmd/godoc/godoc.go:372: header = fmt.Sprintf("\t// ------ Example %s ", example_nameFunc(eg.Name)) On 2013/02/19 06:24:07, adg wrote: > can't we just use indentation to delineate the examples, as we do with all other > blocks of text or code in the text examples? We can, I tried it. But it gets strange for container/heap where two long package level examples have to be presented. If the code is just indented and the second example is separated only by a blank line then there is absolutely no visual clue that this one large block of indented code is actually two examples. How about: A visual separators of the form // ---- Example <name> ------------ is used at the beginning of each example iff more than one example has to be shown in one block.
Sign in to reply to this message.
I suggest that as much as possible godoc -ex should mimic godoc -src. That means that 'godoc -ex strings' should show all the examples in package strings (both package examples and smaller examples), 'godoc -ex strings Fields' shows just the example or examples for Fields, and there's no way to get just the package-level examples. Russ
Sign in to reply to this message.
On 19 February 2013 19:38, <dr.volker.dobler@gmail.com> wrote: > We can, I tried it. But it gets strange for > container/heap where two long package level examples > have to be presented. If the code is just indented > and the second example is separated only by a blank > line then there is absolutely no visual clue that > this one large block of indented code is actually > two examples. > Don't the package-level examples have titles? Surely the title would separate them, not just a blank line?
Sign in to reply to this message.
On Wed, Feb 20, 2013 at 12:38 AM, Andrew Gerrand <adg@golang.org> wrote: > > On 19 February 2013 19:38, <dr.volker.dobler@gmail.com> wrote: > >> We can, I tried it. But it gets strange for >> container/heap where two long package level examples >> have to be presented. If the code is just indented >> and the second example is separated only by a blank >> line then there is absolutely no visual clue that >> this one large block of indented code is actually >> two examples. >> > > Don't the package-level examples have titles? Surely the title would > separate them, not just a blank line? > They do, but the don't separate: Output of container heap would look like below. IMHO the title // Example Package (PriorityQueue) does not "separate" the two examples: If you do not examine each line you'll miss this separation very easily: The large block of code below looks like one large example. Two very long package-level examples might be uncommon and not worth extra handling. If this visual separation is unwanted I'll remove it. $ godoc -ex container/heap PACKAGE 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. A heap is a common way to implement a priority queue. To build a priority queue, implement the Heap interface with the (negative) priority as the ordering for the Less method, so Push adds items while Pop removes the highest-priority item from the queue. The Examples include such an implementation; the file example_pq_test.go has the complete source. // Example Package (IntHeap) // This example demonstrates an integer heap built using the heap interface. package heap_test import ( "container/heap" "fmt" ) // An IntHeap is a min-heap of ints. type IntHeap []int func (h IntHeap) Len() int { return len(h) } func (h IntHeap) Less(i, j int) bool { return h[i] < h[j] } func (h IntHeap) Swap(i, j int) { h[i], h[j] = h[j], h[i] } func (h *IntHeap) Push(x interface{}) { // Push and Pop use pointer receivers because they modify the slice's length, // not just its contents. *h = append(*h, x.(int)) } func (h *IntHeap) Pop() interface{} { old := *h n := len(old) x := old[n-1] *h = old[0 : n-1] return x } // This example inserts several ints into an IntHeap and removes them in order of priority. func Example_intHeap() { h := &IntHeap{2, 1, 5} heap.Init(h) heap.Push(h, 3) for h.Len() > 0 { fmt.Printf("%d ", heap.Pop(h)) } // Output: 1 2 3 5 } // Example Package (PriorityQueue) // This example demonstrates a priority queue built using the heap interface. package heap_test import ( "container/heap" "fmt" ) // An Item is something we manage in a priority queue. type Item struct { value string // The value of the item; arbitrary. priority int // The priority of the item in the queue. // The index is needed by update and is maintained by the heap.Interface methods. index int // The index of the item in the heap. } // A PriorityQueue implements heap.Interface and holds Items. type PriorityQueue []*Item func (pq PriorityQueue) Len() int { return len(pq) } func (pq PriorityQueue) Less(i, j int) bool { // We want Pop to give us the highest, not lowest, priority so we use greater than here. return pq[i].priority > pq[j].priority } func (pq PriorityQueue) Swap(i, j int) { pq[i], pq[j] = pq[j], pq[i] pq[i].index = i pq[j].index = j } func (pq *PriorityQueue) Push(x interface{}) { n := len(*pq) item := x.(*Item) item.index = n *pq = append(*pq, item) } func (pq *PriorityQueue) Pop() interface{} { old := *pq n := len(old) item := old[n-1] item.index = -1 // for safety *pq = old[0 : n-1] return item } // update modifies the priority and value of an Item in the queue. func (pq *PriorityQueue) update(item *Item, value string, priority int) { heap.Remove(pq, item.index) item.value = value item.priority = priority heap.Push(pq, item) } // This example inserts some items into a PriorityQueue, manipulates an item, // and then removes the items in priority order. func Example_priorityQueue() { // Some items and their priorities. items := map[string]int{ "banana": 3, "apple": 2, "pear": 4, } // Create a priority queue and put the items in it. pq := &PriorityQueue{} heap.Init(pq) for value, priority := range items { item := &Item{ value: value, priority: priority, } heap.Push(pq, item) } // Insert a new item and then modify its priority. item := &Item{ value: "orange", priority: 1, } heap.Push(pq, item) pq.update(item, item.value, 5) // Take the items out; they arrive in decreasing priority order. for pq.Len() > 0 { item := heap.Pop(pq).(*Item) fmt.Printf("%.2d:%s ", item.priority, item.value) } // Output: // 05:orange 04:pear 03:banana 02:apple } FUNCTIONS func Init(h Interface) A heap must be initialized before any of the heap operations can be used. Init is idempotent with respect to the heap invariants and may be called whenever the heap invariants may have been invalidated. Its complexity is O(n) where n = h.Len(). [...]
Sign in to reply to this message.
On 20 February 2013 11:41, Volker Dobler <dr.volker.dobler@gmail.com> wrote: > They do, but the don't separate: Output of container heap would > look like below. IMHO the title > // Example Package (PriorityQueue) > does not "separate" the two examples: If you do not examine each > line you'll miss this separation very easily: The large block of code > below looks like one large example. > What if we pulled out the package comment and displayed it one level "outdented"?
Sign in to reply to this message.
PTAL > What if we pulled out the package comment and displayed > it one level "outdented"? That looks really nice, but it is not suitable for the function-, type- and method examples, I thus tried the following: Each example is prefixed by an outdented Example: and the example name is dropped as it was not helpful. The result is pretty and consistent over all examples.
Sign in to reply to this message.
LGTM, but I'd like to wait for gri's signoff.
Sign in to reply to this message.
This will have to wait for tomorrow. - gri On Wed, Feb 20, 2013 at 7:10 PM, <adg@golang.org> wrote: > LGTM, but I'd like to wait for gri's signoff. > > https://codereview.appspot.**com/7356043/<https://codereview.appspot.com/7356... >
Sign in to reply to this message.
LGTM My only concern here is that this ads yet another flag - thus increasing the number of different operation modes that each godoc change must be tested in. Presumably showing the examples always is blowing up the output too much in general? That said, the added code is very self-contained (even the flag use), so maybe we should just see how it goes, as long as we keep in mind that it's harder to take a flag away once people got used to it... Andrew, please feel free to submit if you're happy. Thanks. - gri https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go File src/cmd/godoc/godoc.go (right): https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go#newc... src/cmd/godoc/godoc.go:346: if first { if !first { buf.Writestring("\n") } first = false is simpler (and likely produces less code)
Sign in to reply to this message.
Will submit after this change: On 2013/02/22 06:55:27, gri wrote: > https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go > File src/cmd/godoc/godoc.go (right): > > https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go#newc... > src/cmd/godoc/godoc.go:346: if first { > if !first { > buf.Writestring("\n") > } > first = false > > is simpler (and likely produces less code)
Sign in to reply to this message.
PTAL https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go File src/cmd/godoc/godoc.go (right): https://codereview.appspot.com/7356043/diff/20001/src/cmd/godoc/godoc.go#newc... src/cmd/godoc/godoc.go:346: if first { On 2013/02/22 06:55:27, gri wrote: > if !first { > buf.Writestring("\n") > } > first = false > > is simpler (and likely produces less code) Done.
Sign in to reply to this message.
*** Submitted as https://code.google.com/p/go/source/detail?r=33d3e7bbd3ef *** 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 issue 3587. R=golang-dev, minux.ma, adg, rsc, gri CC=golang-dev https://codereview.appspot.com/7356043 Committer: Andrew Gerrand <adg@golang.org>
Sign in to reply to this message.
|