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]