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

Jump to bottom

cmd/doc: default view does not show methods #28906

Closed
rogpeppe opened this issue Nov 21, 2018 · 4 comments
Closed

cmd/doc: default view does not show methods #28906

rogpeppe opened this issue Nov 21, 2018 · 4 comments
Labels
FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Go1.12

Comments

@rogpeppe
Copy link
Contributor 

$ go version
go version devel +14608976db Thu Nov 15 23:37:20 2018 +0000 linux/amd64

If I run go doc strings, it shows exported functions but not methods:

go doc strings Output
% go doc strings
package strings // import "strings"

Package strings implements simple functions to manipulate UTF-8 encoded

strings.


For information about UTF-8 strings in Go, see

https://blog.golang.org/strings.


func Compare(a, b string) int

func Contains(s, substr string) bool

func ContainsAny(s, chars string) bool

func ContainsRune(s string, r rune) bool

func Count(s, substr string) int

func EqualFold(s, t string) bool

func Fields(s string) []string

func FieldsFunc(s string, f func(rune) bool) []string

func HasPrefix(s, prefix string) bool

func HasSuffix(s, suffix string) bool

func Index(s, substr string) int

func IndexAny(s, chars string) int

func IndexByte(s string, c byte) int

func IndexFunc(s string, f func(rune) bool) int

func IndexRune(s string, r rune) int

func Join(a []string, sep string) string

func LastIndex(s, substr string) int

func LastIndexAny(s, chars string) int

func LastIndexByte(s string, c byte) int

func LastIndexFunc(s string, f func(rune) bool) int

func Map(mapping func(rune) rune, s string) string

func Repeat(s string, count int) string

func Replace(s, old, new string, n int) string

func ReplaceAll(s, old, new string) string

func Split(s, sep string) []string

func SplitAfter(s, sep string) []string

func SplitAfterN(s, sep string, n int) []string

func SplitN(s, sep string, n int) []string

func Title(s string) string

func ToLower(s string) string

func ToLowerSpecial(c unicode.SpecialCase, s string) string

func ToTitle(s string) string

func ToTitleSpecial(c unicode.SpecialCase, s string) string

func ToUpper(s string) string

func ToUpperSpecial(c unicode.SpecialCase, s string) string

func Trim(s string, cutset string) string

func TrimFunc(s string, f func(rune) bool) string

func TrimLeft(s string, cutset string) string

func TrimLeftFunc(s string, f func(rune) bool) string

func TrimPrefix(s, prefix string) string

func TrimRight(s string, cutset string) string

func TrimRightFunc(s string, f func(rune) bool) string

func TrimSpace(s string) string

func TrimSuffix(s, suffix string) string

type Builder struct{ ... }

type Reader struct{ ... }

func NewReader(s string) *Reader

type Replacer struct{ ... }

func NewReplacer(oldnew ...string) *Replacer


BUG: The rule Title uses for word boundaries does not handle Unicode punctuation properly.

There is no indication that (for example) Builder has a bunch of unexported methods.

In the package summaries on godoc.org and golang.org/pkg pages, exported methods are shown (but, like go doc, fields, constants and variables are omitted).

Perhaps go doc should use the same heuristics as godoc.org and include exported methods too.
@mvdan mvdan added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Nov 21, 2018
@mvdan
Copy link
Member

mvdan commented Nov 21, 2018 •
edited

/cc @robpike as per https://dev.golang.org/owners/.

There's go doc -all strings, which does print methods, but it also prints documentation so the output is too large for a quick summary.

It's also interesting that its help line is -all show all documentation for package. Reading that, it seems weird how it affects whether methods are shown as well. Edit: ignore this bit. I just noticed how it says "all the documentation", while I read it as "all the godoc comments".

@FiloSottile FiloSottile changed the title cmd/go: doc does not show methods cmd/doc: default view does not show methods Dec 12, 2018
@FiloSottile
Copy link
Contributor

+1, I find the default go doc view extremely unhelpful on most packages, like crypto/tls, because most functionality is implemented in methods.

/cc @dmitshur

@FiloSottile FiloSottile added this to the Go1.12 milestone Dec 12, 2018
@rsc
Copy link
Contributor

rsc commented Dec 19, 2018

This was done intentionally in the design of go doc to avoid dumping too much. The default view shows you the top-level names in the package and then you can ask for lower things. I find it nice that go doc crypto/tls fits on one screen. If you want to know about the Conn methods, use go doc crypto/tls.Conn (or just go doc tls.Conn).

Given that go doc has had this design for quite a few releases, we're not going to change it now.

@rsc rsc closed this as completed Dec 19, 2018
@ossie-git
Copy link

@rsc I can understand your reasoning. Would it be possible to at least give the user a hint that there are methods not shown? For example, in the github.com/patrickmn/go-cache library, there are dozens of methods. The default behavior is:

$ go doc go-cache
package cache // import "github.com/patrickmn/go-cache"

const NoExpiration time.Duration = -1 ...
type Cache struct{ ... }
    func New(defaultExpiration, cleanupInterval time.Duration) *Cache
    func NewFrom(defaultExpiration, cleanupInterval time.Duration, items map[string]Item) *Cache
type Item struct{ ... }

It would be useful if go doc mentioned that there are methods. For example:

$ go doc go-cache
package cache // import "github.com/patrickmn/go-cache"

const NoExpiration time.Duration = -1 ...
type Cache struct{ ... }
    func New(defaultExpiration, cleanupInterval time.Duration) *Cache
    func NewFrom(defaultExpiration, cleanupInterval time.Duration, items map[string]Item) *Cache
    // suppressed 46 methods
type Item struct{ ... }
    // suppressed 1 method

@golang golang locked and limited conversation to collaborators Sep 24, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Go1.12
Development

No branches or pull requests
6 participants
@rogpeppe @rsc @FiloSottile @mvdan @gopherbot @ossie-git