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: variables and constants in groups are not described properly #5255

Closed
gopherbot opened this issue Apr 10, 2013 · 3 comments
Closed

Comments

@gopherbot
Copy link

by santucco:

Before filing a bug, please check whether it has been fixed since the
latest release. Search the issue tracker and check that you're running the
latest version of Go:

Run "go version" and compare against
http://golang.org/doc/devel/release.html  If a newer version of Go exists,
install it and retry what you did to reproduce the problem.

Thanks.

What steps will reproduce the problem?
If possible, include a link to a program on play.golang.org.
1. Get an attached file test.go
2. go doc test

What is the expected output?
There are variants:
1.
<--------------------------------------------------------->
PACKAGE DOCUMENTATION

package test
    import "test"



CONSTANTS

const (
    Const1 = 1
       Const1
   
    Const2 = 2
       Const2
)

const Const3 = 3
    Const3


VARIABLES

var (
    Var1 int
       Var1

    Var2 string
       Var2
)

var Var3 bool
    Var3
<--------------------------------------------------------->
2.
<--------------------------------------------------------->
PACKAGE DOCUMENTATION

package test
    import "test"



CONSTANTS

const Const1 = 1
    Const1
    
const Const2 = 2
    Const2

const Const3 = 3
    Const3


VARIABLES

var Var1 int
    Var1
    
var Var2 string
    Var2

var Var3 bool
    Var3
<--------------------------------------------------------->

What do you see instead?
<--------------------------------------------------------->
PACKAGE DOCUMENTATION

package test
    import "test"



CONSTANTS

const (

    // Const1
    Const1 = 1
    // Const2
    Const2 = 2
)

const Const3 = 3
    Const3


VARIABLES

var (

    // Var1
    Var1 int
    // Var2
    Var2 string
)

var Var3 bool
    Var3
<--------------------------------------------------------->

Which compiler are you using (5g, 6g, 8g, gccgo)?
6g

Which operating system are you using?
Linux x86_64

Which version are you using?  (run 'go version')
go version devel +1a196137ed09 Tue Apr 09 18:17:55 2013 +1000 linux/amd64

Please provide any additional information below.
Leading newlines in groups are unnecessary too.

Attachments:

  1. test.go (183 bytes)
@ianlancetaylor
Copy link
Contributor

Comment 1:

Owner changed to @griesemer.

@griesemer
Copy link
Contributor

Comment 2:

This is a fine request, but the current godoc and the supporting go/doc were simply not
designed to produce the documentation in the desired form: A group'ed declaration is
considered a single declaration for documentation purposes. If each of those constants
or variables deserves a comment before the variable/constant, consider making them
separate (ungrouped) declarations. That is, there is work-around, and grouping is
intended to get this effect in the documentation.
Removing the extra blank lines in the groups would be desirable, but in general it's not
clear which blank lines are intended by the author, and so it cannot be solved correctly
all the time. Alternatively, godoc might simply ignore user intent, but that's not the
original intention.
In the long run, we may want to redesign godoc (godoc2) and try different approaches.

Status changed to WorkingAsIntended.

@gopherbot
Copy link
Author

Comment 3 by santucco:

Ok, I've got you. I hope the future (possible) redesign  will solve this problem.
Thank you!

@golang golang locked and limited conversation to collaborators Jun 24, 2016
This issue was closed.
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