Commit 4091cf97 authored by Segev Finer's avatar Segev Finer Committed by Rob Pike

cmd/doc: correctly indent pre-formatted blocks

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: 439c0fe70a01490cbd9c3613eba3fe45a3ffd9be
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: default avatarRob Pike <r@golang.org>
parent c1783896
......@@ -721,6 +721,37 @@ var tests = []test{
[]string{"Foo struct"},
nil,
},
{
"formatted doc on function",
[]string{p, "ExportedFormattedDoc"},
[]string{
`func ExportedFormattedDoc\(a int\) bool`,
` Comment about exported function with formatting\.
Example
fmt\.Println\(FormattedDoc\(\)\)
Text after pre-formatted block\.`,
},
nil,
},
{
"formatted doc on type field",
[]string{p, "ExportedFormattedType.ExportedField"},
[]string{
`type ExportedFormattedType struct`,
` // Comment before exported field with formatting\.
//[ ]
// Example
//[ ]
// a\.ExportedField = 123
//[ ]
// Text after pre-formatted block\.`,
`ExportedField int`,
},
nil,
},
}
func TestDoc(t *testing.T) {
......
......@@ -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)
......
......@@ -207,3 +207,25 @@ const (
Duplicate = iota
duplicate
)
// Comment about exported function with formatting.
//
// Example
//
// fmt.Println(FormattedDoc())
//
// Text after pre-formatted block.
func ExportedFormattedDoc(a int) bool {
return true
}
type ExportedFormattedType struct {
// Comment before exported field with formatting.
//
// Example
//
// a.ExportedField = 123
//
// Text after pre-formatted block.
ExportedField int
}
Markdown is supported
0%
or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment