go/doc: confused by //line comments #5247

gopherbot · 2013-04-09T09:44:00Z

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. go get bitbucket.org/santucco/goplumb
2. go doc bitbucket.org/santucco/goplumb

What is the expected output?
<--------------------------------------------------------->
PACKAGE DOCUMENTATION

package goplumb
    import "bitbucket.org/santucco/goplumb"

    Package goplumb provides interface to plumber - interprocess messaging
    from Plan 9.


VARIABLES

var (

    //PlumberDir is a default mount point of plumber.
    PlumberDir string = "/mnt/plumb/"
)


FUNCTIONS

func Pack(message *Message) []byte
    Pack packs a message to []byte.

func PackAttr(attr []Attr) string
    PackAttr packs attr to string. If an attribute value
    contains a white space, a quote or an equal sign the value will be
    quoted.

func UnpackAttr(s string) []Attr
    UnpackAttr unpack the attributes from s


TYPES

type Attr struct {
    Name  string
    Value string
}
    Attr is a description of an attribute of a plumber
    message.



type Message struct {
    Src  string
    Dst  string
    Wdir string
    Type string
    Attr []Attr
    Data []byte
}
    Message desribes a plumber message.


func Unpack(b []byte) *Message
    Unpack return unpacked message.

func UnpackPartial(b []byte) (m *Message, r int)
    UnpackPartial helps to unpack messages splited in
    peaces. The first call to UnpackPartial for a given message must be
    sufficient to unpack the header; subsequent calls permit unpacking
    messages with long data sections. For each call, b contans the complete
    message received so far. If the message is complete, a pointer to the
    resulting message m will be returned, and a number of remainings bytes r
    will be set to 0. Otherwise m will be nil and r will be set to the
    number of bytes remaining to be read for this message to be complete
    (recall that the byte count is in the header). Those bytes should be
    read by the caller, placed at location b[r:], and the message unpacked
    again. If an error is encountered, m will be nil and r will be zero.



type Plumb struct {
    // contains filtered or unexported fields
}


func Open(port string, omode int) (*Plumb, error)
    Open opens a specified port with a specified omode. If the port begin
    with a slash, it is taken as a literal file name, otherwise it is a file
    name in the plumber file system at PlumberDir.


func (this *Plumb) Close()
    Close closes a plumbing connection.

func (this *Plumb) Recv() (*Message, error)
    Recv returns a received message or an error.

func (this *Plumb) Send(message *Message) error
    Send sends a message.

func (this *Plumb) SendText(src string, dst string, wdir string, data string) error
    SendText sends a text-only message; it assumes Type
    is text and Attr is empty.
<--------------------------------------------------------->

What do you see instead?

<--------------------------------------------------------->
PACKAGE DOCUMENTATION

package goplumb
    import "bitbucket.org/santucco/goplumb"

    Package goplumb provides interface to plumber - interprocess messaging
    from Plan 9.


VARIABLES

var (

    //PlumberDir is a default mount point of plumber.
    PlumberDir string = "/mnt/plumb/"
)


FUNCTIONS

func Pack(message *Message) []byte
    line goplumb.w:255 Pack packs a message to []byte.

func PackAttr(attr []Attr) string
    line goplumb.w:269 PackAttr packs attr to string. If an attribute value
    contains a white space, a quote or an equal sign the value will be
    quoted.

func UnpackAttr(s string) []Attr
    UnpackAttr unpack the attributes from s


TYPES

type Attr struct {
    Name  string
    Value string
}
    line goplumb.w:176 Attr is a description of an attribute of a plumber
    message.



type Message struct {
    Src  string
    Dst  string
    Wdir string
    Type string
    Attr []Attr
    Data []byte
}
    Message desribes a plumber message.


func Unpack(b []byte) *Message
    Unpack return unpacked message.

func UnpackPartial(b []byte) (m *Message, r int)
    line goplumb.w:399 UnpackPartial helps to unpack messages splited in
    peaces. The first call to UnpackPartial for a given message must be
    sufficient to unpack the header; subsequent calls permit unpacking
    messages with long data sections. For each call, b contans the complete
    message received so far. If the message is complete, a pointer to the
    resulting message m will be returned, and a number of remainings bytes r
    will be set to 0. Otherwise m will be nil and r will be set to the
    number of bytes remaining to be read for this message to be complete
    (recall that the byte count is in the header). Those bytes should be
    read by the caller, placed at location b[r:], and the message unpacked
    again. If an error is encountered, m will be nil and r will be zero.



type Plumb struct {
    // contains filtered or unexported fields
}


func Open(port string, omode int) (*Plumb, error)
    Open opens a specified port with a specified omode. If the port begin
    with a slash, it is taken as a literal file name, otherwise it is a file
    name in the plumber file system at PlumberDir.


func (this *Plumb) Close()
    line goplumb.w:520 Close closes a plumbing connection.

func (this *Plumb) Recv() (*Message, error)
    line goplumb.w:309 Recv returns a received message or an error.

func (this *Plumb) Send(message *Message) error
    Send sends a message.

func (this *Plumb) SendText(src string, dst string, wdir string, data string) error
    line goplumb.w:288 SendText sends a text-only message; it assumes Type
    is text and Attr is empty.
<--------------------------------------------------------->

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.
The project bitbucket.org/santucco/goplumb is "literate programmed" and the
file goplumb.go is generated from goplumb.w.
The line marks  (//line goplumb.w:xxx) are added in goplumb.go when it is being
generated. They are separated from comments of description by newline, but for some
reason sometimes they are added to the descriptions.
I tried to process goplumb.go by gofmt, the result was changed a bit, but the most of
line marks were left.

ianlancetaylor · 2013-04-09T18:12:03Z

Comment 1:

Owner changed to @griesemer.

griesemer · 2013-04-09T18:15:17Z

Comment 2:

Status changed to Accepted.

bradfitz · 2013-05-13T18:26:20Z

Comment 3:

Labels changed: removed priority-triage.

rsc · 2013-07-30T15:26:54Z

Comment 4:

Labels changed: added go1.2.

rsc · 2013-09-09T17:42:00Z

Comment 5:

I looked briefly into this. Boiled down example:
package p
//line file:2
// G doc.
func G()
but change the line number to file:10 and the comment is correctly dropped. It appears
that the problem is that various pieces of the parser assume they can do comparisons
against the raw line number returned by f.Line(pos), but they cannot: they need to
compare against both the file and the line number.
Or perhaps the token.File needs to expose a RawLine() int that is 1 + the actual number
of \ns before that point in the input, meaning the line number ignoring //line
directives, and then the parser would use that.
Not going to happen for Go 1.2.

Labels changed: added go1.3, removed go1.2.

rsc · 2013-12-04T01:30:05Z

Comment 6:

Labels changed: added release-go1.3.

rsc · 2013-12-04T01:30:26Z

Comment 7:

Labels changed: removed go1.3.

rsc · 2013-12-04T01:47:46Z

Comment 8:

Labels changed: added repo-main.

griesemer · 2014-04-02T23:23:40Z

Comment 9:

The underlying problem is that token.Positions report positions as modified via //line
comments. To properly solve this, we need access to both the original (non-modified)
line positions, and the modified line positions. This requires an API change (adding
another position accessor), and may have complex consequences for clients of token
positions if we change the semantics of the current Position accessor.
For instance, commenting out go/token/position.go:272-281, which means "ignore //line
comments" resolves this specific test case.
Russ suggests providing another accessor, go/token.File.RawLine (which would also
require go/token.File.RawPosition). gofmt would only rely on raw positions, since it
formats the raw source irrespective of how that source was generated.
Alternatively, one might provide go/token.File.ModifiedLine, and ModifiedPosition, which
would take the role of the current Line and Position accessors, and the current Line and
Position accessors would provide the raw information instead. This would make sense if
most tools cared mostly about the actual position of the incoming Go source code, rather
than the //line-directed source positions.
There may also be a chance we can circumvent the issue by using the go/printer.SourcePos
mode with gofmt (simply setting it though didn't resolve the issue - there may be other
bugs).
Marking Go1.3Maybe for now.

Labels changed: added release-go1.3maybe, removed release-go1.3.

garyburd · 2014-04-02T23:30:23Z

Comment 10:

godoc.org handles this issue by overwriting the line comments with spaces before parsing
the file.

griesemer · 2014-04-02T23:52:50Z

Comment 11:

#10: I'd call this a very creative "just-in-time" hack :-) It does work, indeed. Will
have a 1.3 CL tomorrow.

griesemer · 2014-04-03T18:13:02Z

Comment 12:

Pending CL: https://golang.org/cl/84050044
Also: Filed issue #7702 for a true fix (for 1.4).

Status changed to Started.

griesemer · 2014-04-03T20:13:10Z

Comment 13:

This issue was closed by revision golang/tools@55ea531.

Status changed to Fixed.

gopherbot added fixed labels Apr 3, 2014

gopherbot assigned griesemer Apr 3, 2014

rsc added this to the Go1.3 milestone Apr 14, 2015

rsc removed the release-go1.3maybe label Apr 14, 2015

golang locked and limited conversation to collaborators Jun 24, 2016

gopherbot added the FrozenDueToAge label Jun 24, 2016

rsc unassigned griesemer Jun 22, 2022

This issue was closed.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

go/doc: confused by //line comments #5247

go/doc: confused by //line comments #5247

gopherbot commented Apr 9, 2013

ianlancetaylor commented Apr 9, 2013

griesemer commented Apr 9, 2013

bradfitz commented May 13, 2013

rsc commented Jul 30, 2013

rsc commented Sep 9, 2013

rsc commented Dec 4, 2013

rsc commented Dec 4, 2013

rsc commented Dec 4, 2013

griesemer commented Apr 2, 2014

garyburd commented Apr 2, 2014

griesemer commented Apr 2, 2014

griesemer commented Apr 3, 2014

griesemer commented Apr 3, 2014

go/doc: confused by //line comments #5247

go/doc: confused by //line comments #5247

Comments

gopherbot commented Apr 9, 2013

ianlancetaylor commented Apr 9, 2013

griesemer commented Apr 9, 2013

bradfitz commented May 13, 2013

rsc commented Jul 30, 2013

rsc commented Sep 9, 2013

rsc commented Dec 4, 2013

rsc commented Dec 4, 2013

rsc commented Dec 4, 2013

griesemer commented Apr 2, 2014

garyburd commented Apr 2, 2014

griesemer commented Apr 2, 2014

griesemer commented Apr 3, 2014

griesemer commented Apr 3, 2014