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: not printing package name in type query #31457

Closed
rsc opened this issue Apr 13, 2019 · 4 comments
Closed

cmd/doc: not printing package name in type query #31457

rsc opened this issue Apr 13, 2019 · 4 comments
Milestone

Comments

@rsc
Copy link
Contributor

rsc commented Apr 13, 2019

go doc big.NewInt tells me what package it is talking about:

$ go doc big.NewInt
package big // import "math/big"

func NewInt(x int64) *Int
    NewInt allocates and returns a new Int set to x.

$ 

but go doc big.Int does not:

$ go doc big.Int
type Int struct {
	// Has unexported fields.
}
    An Int represents a signed multi-precision integer. The zero value for an
    Int represents the value 0.

    Operations always take pointer arguments (*Int) rather than Int values, and
    each unique Int value requires its own unique *Int pointer. To "copy" an Int
    value, an existing (or newly allocated) Int must be set to a new value using
    the Int.Set method; shallow copies of Ints are not supported and may lead to
    errors.

func NewInt(x int64) *Int
func (z *Int) Abs(x *Int) *Int
func (z *Int) Add(x, y *Int) *Int
...

It seems like the package line should be printed always, and there is just a bug in this code path.

/cc @robpike

@rsc rsc added this to the Go1.13 milestone Apr 13, 2019
@rsc rsc changed the title cmd/doc: not printing package name cmd/doc: not printing package name in type query Apr 13, 2019
@robpike robpike self-assigned this Apr 13, 2019
@robpike
Copy link
Contributor

robpike commented Apr 13, 2019

There's inconsistency for sure; this one doesn't print the package either:

% go doc fmt.printf
func Printf(format string, a ...interface{}) (n int, err error)
    Printf formats according to a format specifier and writes to standard
    output. It returns the number of bytes written and any write error
    encountered.

% 

Should the package always be printed? Maybe. Or maybe just if the arguments don't match the package name?

There's also this, which is annoying. If I run that command in my home directory, not in a module directory, I get a distracting message containing nothing mentioned on the command line:

bismarck=% go doc fmt.printf
warning: pattern "all" matched no module dependencies
func Printf(format string, a ...interface{}) (n int, err error)
...

@gopherbot
Copy link

Change https://golang.org/cl/177797 mentions this issue: cmd/doc: always print package clause except for commands

@gopherbot
Copy link

Change https://golang.org/cl/182619 mentions this issue: doc: add release notes for godoc and go doc

gopherbot pushed a commit that referenced this issue Jun 21, 2019
Updates #30029
Updates #31457

Change-Id: I08414a544615e74afb47f7a10a00f1e22adfd40c
Reviewed-on: https://go-review.googlesource.com/c/go/+/182619
Reviewed-by: Katie Hockman <katie@golang.org>
@gopherbot
Copy link

Change https://golang.org/cl/206128 mentions this issue: cmd/doc: show the package clause always

gopherbot pushed a commit that referenced this issue Nov 12, 2019
If no writes to the package buffer happen, then the package clause
does not get printed. This is a bug for cases where a file just contains
the package clause.

We fix this by separating the printing of package clause to a new
function and calling it from (*pkgBuffer).Write as well as (*Package).flush.

Updates #31457

Change-Id: Ia3bd0ea3963274c460a45d1e37fafc6ee0a197f0
Reviewed-on: https://go-review.googlesource.com/c/go/+/206128
Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
@golang golang locked and limited conversation to collaborators Nov 10, 2020
@rsc rsc unassigned robpike Jun 23, 2022
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