Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

cmd/doc: print example code and output #56073

Closed
nickjwhite opened this issue Oct 6, 2022 · 2 comments
Closed

cmd/doc: print example code and output #56073

nickjwhite opened this issue Oct 6, 2022 · 2 comments

Comments

@nickjwhite
Copy link

nickjwhite commented Oct 6, 2022

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/doc Package 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]

@seankhliao
Copy link
Member

Duplicate of #26715

@seankhliao seankhliao marked this as a duplicate of #26715 Oct 6, 2022
@seankhliao seankhliao closed this as not planned Won't fix, can't repro, duplicate, stale Oct 6, 2022
@nickjwhite
Copy link
Author

Apologies for the duplicate @seankhliao, I did search the issue tracker, obviously not well enough!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants