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: output can be hard to read #12756

Closed
dsnet opened this issue Sep 25, 2015 · 1 comment
Closed

cmd/doc: output can be hard to read #12756

dsnet opened this issue Sep 25, 2015 · 1 comment

Comments

@dsnet
Copy link
Member

dsnet commented Sep 25, 2015

This is obviously subjective. Kindly close it if people disagree.

Using 59129c6a9356af5831b3f0a4bc581ba6abf26c8a.


What I see:

$ go doc io.read
func (l *LimitedReader) Read(p []byte) (n int, err error)
func (r *PipeReader) Read(data []byte) (n int, err error)

    Read implements the standard Read interface: it reads data from the pipe,
    blocking until a writer arrives or the write end is closed. If the write end
    is closed with an error, that error is returned as err; otherwise err is
    EOF.
func (s *SectionReader) Read(p []byte) (n int, err error)

What I expect:

$ go doc io.read
func (l *LimitedReader) Read(p []byte) (n int, err error)
func (r *PipeReader) Read(data []byte) (n int, err error)
    Read implements the standard Read interface: it reads data from the pipe,
    blocking until a writer arrives or the write end is closed. If the write end
    is closed with an error, that error is returned as err; otherwise err is
    EOF.

func (s *SectionReader) Read(p []byte) (n int, err error)

In this situation, it looks like the function description applies to SectionReader.Read, when it actually applies to PipeReader.Read


What I see:

$ go doc io
package io // import "io"

Package io provides basic interfaces to I/O primitives. Its primary job is
to wrap existing implementations of such primitives, such as those in
package os, into shared public interfaces that abstract the functionality,
plus some other related primitives.

Because these interfaces and primitives wrap lower-level operations with
various implementations, unless otherwise informed clients should not assume
they are safe for parallel execution.
var EOF = errors.New("EOF")
var ErrClosedPipe = errors.New("io: read/write on closed pipe")
var ErrNoProgress = errors.New("multiple Read calls return no data or error")
...

What I expect:

$ go doc io
package io // import "io"

Package io provides basic interfaces to I/O primitives. Its primary job is
to wrap existing implementations of such primitives, such as those in
package os, into shared public interfaces that abstract the functionality,
plus some other related primitives.

Because these interfaces and primitives wrap lower-level operations with
various implementations, unless otherwise informed clients should not assume
they are safe for parallel execution.

var EOF = errors.New("EOF")
var ErrClosedPipe = errors.New("io: read/write on closed pipe")
var ErrNoProgress = errors.New("multiple Read calls return no data or error")
...

In this situation, there is no newline between the package description and the package contents. Thus, it is hard for the human reader to quickly identify what components exist in the package.

@gopherbot
Copy link

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

@rakyll rakyll modified the milestone: Unplanned Sep 26, 2015
@golang golang locked and limited conversation to collaborators Sep 27, 2016
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Projects
None yet
Development

No branches or pull requests

3 participants