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

go/doc: blank line at beginning of type when first fields are unexported #29049

Closed
mark-rushakoff opened this issue Dec 1, 2018 · 1 comment

Comments

@mark-rushakoff
Copy link
Contributor

Given a go file with structs and interfaces that have an unexported field/method followed by an exported field/method:

package e

type A struct {
	hidden int

	Visible int
}

type B struct {
	hidden int

	// Visible is exported.
	Visible int
}

type C interface {
	hidden()

	Visible()
}

type D interface {
	hidden()

	// Visible is exported.
	Visible()
}

then running for type in A B C D; do go doc . $type; done, for go version go version go1.11.2 darwin/amd64, prints:

package e // import "."

type A struct {
	Visible int
	// Has unexported fields.
}
package e // import "."

type B struct {

	// Visible is exported.
	Visible int
	// Has unexported fields.
}
package e // import "."

type C interface {
	Visible()
	// Has unexported methods.
}
package e // import "."

type D interface {

	// Visible is exported.
	Visible()
	// Has unexported methods.
}

For tip version go version devel +950100a95c Fri Nov 30 19:11:39 2018 +0000 darwin/amd64, the above loop prints:

type A struct {
	Visible int
	// Has unexported fields.
}

type B struct {

	// Visible is exported.
	Visible int
	// Has unexported fields.
}

type C interface {
	Visible()
	// Has unexported methods.
}

type D interface {

	// Visible is exported.
	Visible()
	// Has unexported methods.
}

which is the same effective output, except it doesn't contain the package e // import "." lines. I skimmed through the issues involving doc for the Go 1.12 milestone and I didn't notice whether that was a deliberate change, so that may be a separate issue altogether.

For types B and D, which have a godoc comment associated with the exported field/method, there is a leading blank line inside the type. Types A and C do not have godoc for the exported field/method and go doc does not produce a leading blank line for them.

The leading blank line for B and D seems to be unnecessary visual stutter. It would be better if the output did not have any leading blank lines in the types, like so:

type A struct {
	Visible int
	// Has unexported fields.
}

type B struct {
	// Visible is exported.
	Visible int
	// Has unexported fields.
}

type C interface {
	Visible()
	// Has unexported methods.
}

type D interface {
	// Visible is exported.
	Visible()
	// Has unexported methods.
}

I first noticed the leading blank line on the godoc for runtime.MemStats: https://tip.golang.org/pkg/runtime/#MemStats. I'm not sure what other standard library types are printed this way, if any.

@agnivade
Copy link
Contributor

agnivade commented Dec 1, 2018

Duplicate of #18264.

There are some nuances to this. It was fixed and then reverted.

@agnivade agnivade closed this as completed Dec 1, 2018
@golang golang locked and limited conversation to collaborators Dec 1, 2019
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