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: 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>

src/cmd/doc/doc_test.go

@@ -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) {

src/cmd/doc/pkg.go

@@ -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)

src/cmd/doc/testdata/pkg.go

@@ -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
+}