You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
go doc currently doesn't include example code and output included in a package (see https://go.dev/blog/examples and https://pkg.go.dev/testing#hdr-Examples for what I'm talking about). These are often very useful for understanding how code should be used, and it's a pain to have to check on the pkgsite to see if there are examples.
This could be gated behind a flag (maybe -e or -ex) to keep the current behavior as default. Personally I'd favor always printing example code & output if a specific symbol is requested (go doc sort Strings), but (other than package level examples) not print them when documenting the whole package (go doc sort).
Current state of affairs:
$ go doc sort Strings
package sort // import "sort"
func Strings(x []string)
Strings sorts a slice of strings in increasing order.
Proposed output:
$ go doc sort Strings
package sort // import "sort"
func Strings(x []string)
Strings sorts a slice of strings in increasing order.
Example:
s := []string{"Go", "Bravo", "Gopher", "Alpha", "Grin", "Delta"}
sort.Strings(s)
fmt.Println(s)
// Output: [Alpha Bravo Delta Go Gopher Grin]
This shouldn't require a big change, as the go/docPackage that's used by cmd/doc already includes an Examples []*Example field. I'd like to have a go at implementing this, if nobody objects to the idea.
[edited to switch from pkgsite's approach of adding necessary imports etc for a self-contained program to just include the code in the Example*() function code]
The text was updated successfully, but these errors were encountered:
go doc
currently doesn't include example code and output included in a package (see https://go.dev/blog/examples and https://pkg.go.dev/testing#hdr-Examples for what I'm talking about). These are often very useful for understanding how code should be used, and it's a pain to have to check on the pkgsite to see if there are examples.This could be gated behind a flag (maybe
-e
or-ex
) to keep the current behavior as default. Personally I'd favor always printing example code & output if a specific symbol is requested (go doc sort Strings
), but (other than package level examples) not print them when documenting the whole package (go doc sort
).Current state of affairs:
Proposed output:
This shouldn't require a big change, as the
go/doc
Package
that's used bycmd/doc
already includes anExamples []*Example
field. I'd like to have a go at implementing this, if nobody objects to the idea.[edited to switch from pkgsite's approach of adding necessary imports etc for a self-contained program to just include the code in the Example*() function code]
The text was updated successfully, but these errors were encountered: