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

go/doc: group constructors with types #14004

Closed
aclements opened this issue Jan 18, 2016 · 3 comments
Closed

go/doc: group constructors with types #14004

aclements opened this issue Jan 18, 2016 · 3 comments
Labels
FrozenDueToAge
Milestone
Unplanned

Comments

@aclements
Copy link
Member

The godoc tool groups constructors with the types they construct in the package index. This is incredibly useful for organizing documentation and quickly understanding the relationships between package symbols.

In contrast, while the go doc tool does this grouping when you ask for a particular type's documentation, for package documentation it prints all functions before it prints types. It would be nice if the package documentation was grouped similarly to what godoc does.

For example, the current go doc output for "go doc reflect" looks like:

$ go doc reflect
...
func Copy(dst, src Value) int
func DeepEqual(x, y interface{}) bool
func Select(cases []SelectCase) (chosen int, recv Value, recvOK bool)
func ArrayOf(count int, elem Type) Type
func ChanOf(dir ChanDir, t Type) Type
func FuncOf(in, out []Type, variadic bool) Type
func MapOf(key, elem Type) Type
func PtrTo(t Type) Type
func SliceOf(t Type) Type
func TypeOf(i interface{}) Type
func Append(s Value, x ...Value) Value
func AppendSlice(s, t Value) Value
func Indirect(v Value) Value
func MakeChan(typ Type, buffer int) Value
func MakeFunc(typ Type, fn func(args []Value) (results []Value)) Value
func MakeMap(typ Type) Value
func MakeSlice(typ Type, len, cap int) Value
func New(typ Type) Value
func NewAt(typ Type, p unsafe.Pointer) Value
func ValueOf(i interface{}) Value
func Zero(typ Type) Value
type ChanDir int
type Kind uint
type Method struct { ... }
type SelectCase struct { ... }
type SelectDir int
type SliceHeader struct { ... }
type StringHeader struct { ... }
type StructField struct { ... }
type StructTag string
type Type interface { ... }
type Value struct { ... }
type ValueError struct { ... }
...

Something is clearly putting constructor functions together, but they're printed separately from the type they construct. This would be much clearer if it were something like the following:

$ go doc reflect
...
func Copy(dst, src Value) int
func DeepEqual(x, y interface{}) bool
func Select(cases []SelectCase) (chosen int, recv Value, recvOK bool)
type ChanDir int
type Kind uint
type Method struct { ... }
type SelectCase struct { ... }
type SelectDir int
type SliceHeader struct { ... }
type StringHeader struct { ... }
type StructField struct { ... }
type StructTag string
type Type interface { ... }
    func ArrayOf(count int, elem Type) Type
    func ChanOf(dir ChanDir, t Type) Type
    func FuncOf(in, out []Type, variadic bool) Type
    func MapOf(key, elem Type) Type
    func PtrTo(t Type) Type
    func SliceOf(t Type) Type
    func TypeOf(i interface{}) Type
type Value struct { ... }
    func Append(s Value, x ...Value) Value
    func AppendSlice(s, t Value) Value
    func Indirect(v Value) Value
    func MakeChan(typ Type, buffer int) Value
    func MakeFunc(typ Type, fn func(args []Value) (results []Value)) Value
    func MakeMap(typ Type) Value
    func MakeSlice(typ Type, len, cap int) Value
    func New(typ Type) Value
    func NewAt(typ Type, p unsafe.Pointer) Value
    func ValueOf(i interface{}) Value
    func Zero(typ Type) Value
type ValueError struct { ... }
...

/cc @robpike @griesemer
@robpike
Copy link
Contributor

robpike commented Jan 18, 2016 

go doc reflect.Type

prints what you want. That's not an argument for or against doing what you ask for.

@aclements
Copy link
Member Author

go doc reflect.Type prints what you want.

Yes, I'm aware of that. And I find it so useful for understanding the structure of the package that I think the package overview should do it, too.

@bradfitz bradfitz added this to the Unplanned milestone Jan 21, 2016
@gopherbot
Copy link

CL https://golang.org/cl/22354 mentions this issue.

@dsnet dsnet mentioned this issue Aug 2, 2016
Closed
@mvdan mvdan mentioned this issue Nov 27, 2016
Closed
@golang golang locked and limited conversation to collaborators Apr 21, 2017
@rsc rsc unassigned robpike Jun 23, 2022
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge
Projects
None yet
Milestone
Unplanned
Development

No branches or pull requests
4 participants
@bradfitz @aclements @robpike @gopherbot