Pretty sure this is a bug in go/doc's ToText function. cmd/doc calls that to format comments.

@griesemer?

Hard to see this as a release blocker, though. Demoting to Maybe.

This is due to indentedWidth being 76 in doc.ToText in src/cmd/doc/pkg.go.(*pkg printFieldDoc). So when the last line of comment is being printed, the lineWrapper wraps it in the next line but does not add a // for the next line of comment.

This does not happen in go doc csv.Reader because the printing of the Reader type is done by format.Node which does not have any line wrapping logic.

To fix this, we need to add logic to lineWrapper to check if it is printing a comment and add a // in the next line. Currently, ToText is not aware that whether it is printing a comment or any random text. Although the doc comment does say that // ToText prepares comment text for presentation in textual output.

@griesemer - Are you okay with this ? In general, are there cases where doc.ToText is called for something which is not a comment ? From a cursory grep, it does not appear so.

Also what about block comments ? I have never seen block comments in struct fields, but I guess it is plausible some people can use it. The formatting screws up even further if I use them

gotip run . csv.Reader.ReuseRecord
type Reader struct {
    /* ReuseRecord controls whether calls to Read may return a slice sharing

    the backing array of the previous call's returned slice for performance.
    By default, each call to Read returns newly allocated memory owned by the caller. */    ReuseRecord bool

    // ... other fields elided ...
}

Whatever lineWrapper is doing, it needs to be aware of whether it's in a comment (and what kind of comment), and do the right thing. Looks like this is clearly a bug that should be addressed.

Change https://golang.org/cl/163578 mentions this issue: go/doc: add // while wrapping a line comment in ToText