cmd/doc: rearrange the newlines to group better
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>
diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go
index b90019d..0aef208 100644
--- a/src/cmd/doc/pkg.go
+++ b/src/cmd/doc/pkg.go
@@ -169,10 +169,12 @@
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 @@
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)
