Stowage/go
2
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-12-08 06:10:04 +00:00
Code Issues Projects Releases Packages Wiki Activity

cmd/doc: rearrange the newlines to group better

Browse source 
Main change is that the comment for an item no longer has a blank line
before it, so it looks bound to the item it's about.

Motivating example: go doc.io.read changes from

<
func (l *LimitedReader) Read(p []byte) (n int, err error)
func (r *PipeReader) Read(data []byte) (n int, err error)

    Read implements the standard Read interface: it reads data from the pipe,
    blocking until a writer arrives or the write end is closed. If the write end
    is closed with an error, that error is returned as err; otherwise err is
    EOF.
func (s *SectionReader) Read(p []byte) (n int, err error)
>

to

<
func (l *LimitedReader) Read(p []byte) (n int, err error)
func (r *PipeReader) Read(data []byte) (n int, err error)
    Read implements the standard Read interface: it reads data from the pipe,
    blocking until a writer arrives or the write end is closed. If the write end
    is closed with an error, that error is returned as err; otherwise err is
    EOF.

func (s *SectionReader) Read(p []byte) (n int, err error)
>

Now the comment about PipeReader.Read doesn't look like it's about
SectionReader.

Based on a suggestion by dsnet@, a slight tweak from a CL he suggested
and abandoned.

Fixes #12756,

Change-Id: Iaf60ee9ae7f644c83c32d5e130acab0312b0c926
Reviewed-on: https://go-review.googlesource.com/14999
Reviewed-by: Andrew Gerrand <adg@golang.org>
This commit is contained in:
Rob Pike 2015-09-25 16:04:30 -07:00
parent 12dfc3bee4
commit c978f13a71
1 changed files with 5 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

8
src/cmd/doc/pkg.go
View file

@ -169,10 +169,12 @@ func (pkg *Package) emit(comment string, node ast.Node) {
log.Fatal(err)
}
if comment != "" {
pkg.newlines(2) // Guarantee blank line before comment.
pkg.newlines(1)
doc.ToText(&pkg.buf, comment, " ", indent, indentedWidth)
pkg.newlines(2) // Blank line after comment to separate from next item.
} else {
pkg.newlines(1)
}
pkg.newlines(1)
}
}
@ -247,7 +249,7 @@ func (pkg *Package) packageDoc() {
return
}
pkg.newlines(1)
pkg.newlines(2) // Guarantee blank line before the components.
pkg.valueSummary(pkg.doc.Consts)
pkg.valueSummary(pkg.doc.Vars)
pkg.funcSummary(pkg.doc.Funcs)