From 4091cf972a37418c847426bd15709cd0128fad81 Mon Sep 17 00:00:00 2001 From: Segev Finer Date: Fri, 29 Mar 2019 09:35:06 +0000 Subject: [PATCH] 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 TryBot-Result: Gobot Gobot Reviewed-by: Rob Pike --- src/cmd/doc/doc_test.go | 31 +++++++++++++++++++++++++++++++ src/cmd/doc/pkg.go | 12 +++++++++--- src/cmd/doc/testdata/pkg.go | 22 ++++++++++++++++++++++ 3 files changed, 62 insertions(+), 3 deletions(-) diff --git a/src/cmd/doc/doc_test.go b/src/cmd/doc/doc_test.go index 5532cf537d..22468db1ff 100644 --- a/src/cmd/doc/doc_test.go +++ b/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) { diff --git a/src/cmd/doc/pkg.go b/src/cmd/doc/pkg.go index e3a44c4283..12b76c2ad0 100644 --- a/src/cmd/doc/pkg.go +++ b/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) diff --git a/src/cmd/doc/testdata/pkg.go b/src/cmd/doc/testdata/pkg.go index 88e8c215d0..759b7723a6 100644 --- a/src/cmd/doc/testdata/pkg.go +++ b/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 +} -- 2.48.1