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: correctly indent pre-formatted blocks

Browse source 
They were previously indented at the same level as the normal text when
printing a single symbol or the description of a field.

Running "go doc text/template Must":
Before:
    func Must(t *Template, err error) *Template
        Must is a helper that wraps a call to a function returning (*Template,
        error) and panics if the error is non-nil. It is intended for use in
        variable initializations such as

        var t = template.Must(template.New("name").Parse("text"))

After:
    func Must(t *Template, err error) *Template
        Must is a helper that wraps a call to a function returning (*Template,
        error) and panics if the error is non-nil. It is intended for use in
        variable initializations such as

            var t = template.Must(template.New("name").Parse("text"))

Running "go doc http Request.Header":
Before:
    type Request struct {
        // Header contains the request header fields either received
        // by the server or to be sent by the client.
        //
        // If a server received a request with header lines,
        //
        // Host: example.com
        // accept-encoding: gzip, deflate
        // Accept-Language: en-us
        // fOO: Bar
        // foo: two
        //
        // then
        //
        // Header = map[string][]string{
        // "Accept-Encoding": {"gzip, deflate"},
        // "Accept-Language": {"en-us"},
        // "Foo": {"Bar", "two"},
        // }
        ...

After:
    type Request struct {
        // Header contains the request header fields either received by the server or
        // to be sent by the client.
        //
        // If a server received a request with header lines,
        //
        //     Host: example.com
        //     accept-encoding: gzip, deflate
        //     Accept-Language: en-us
        //     fOO: Bar
        //     foo: two
        //
        // then
        //
        //     Header = map[string][]string{
        //          "Accept-Encoding": {"gzip, deflate"},
        //          "Accept-Language": {"en-us"},
        //          "Foo": {"Bar", "two"},
        //     }
        ...

Fixes #29708

Change-Id: Ibe1a6a7a76d6b19c5737ba6e8210e3ad0b88ce16
GitHub-Last-Rev: 439c0fe70a
GitHub-Pull-Request: golang/go#31120
Reviewed-on: https://go-review.googlesource.com/c/go/+/169957
Run-TryBot: Rob Pike <r@golang.org>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
This commit is contained in:
Segev Finer 2019-03-29 09:35:06 +00:00 • committed by Rob Pike
parent c178389604
commit 4091cf972a
3 changed files with 62 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

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

@ -5,6 +5,7 @@
package main
import (
"bufio"
"bytes"
"fmt"
"go/ast"
@ -221,7 +222,7 @@ func (pkg *Package) emit(comment string, node ast.Node) {
}
if comment != "" && !showSrc {
pkg.newlines(1)
doc.ToText(&pkg.buf, comment, " ", indent, indentedWidth)
doc.ToText(&pkg.buf, comment, indent, indent+indent, indentedWidth)
pkg.newlines(2) // Blank line after comment to separate from next item.
} else {
pkg.newlines(1)
@ -1005,8 +1006,13 @@ func (pkg *Package) printFieldDoc(symbol, fieldName string) bool {
pkg.Printf("type %s struct {\n", typ.Name)
}
if field.Doc != nil {
for _, comment := range field.Doc.List {
doc.ToText(&pkg.buf, comment.Text, indent, indent, indentedWidth)
// To present indented blocks in comments correctly, process the comment as
// a unit before adding the leading // to each line.
docBuf := bytes.Buffer{}
doc.ToText(&docBuf, field.Doc.Text(), "", indent, indentedWidth)
scanner := bufio.NewScanner(&docBuf)
for scanner.Scan() {
fmt.Fprintf(&pkg.buf, "%s// %s\n", indent, scanner.Bytes())
}
}
s := pkg.oneLineNode(field.Type)