diff options
author | Segev Finer <segev208@gmail.com> | 2019-03-29 09:35:06 +0000 |
---|---|---|
committer | Rob Pike <r@golang.org> | 2019-03-31 23:35:35 +0000 |
commit | 4091cf972a37418c847426bd15709cd0128fad81 (patch) | |
tree | 3c0520b2fe5669b3c12b822d196f9312f73c23b7 /src/cmd/doc | |
parent | c1783896049a4e0b4b8834ca02e0914b8d03de79 (diff) | |
download | go-4091cf972a37418c847426bd15709cd0128fad81.tar.gz go-4091cf972a37418c847426bd15709cd0128fad81.zip |
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: Rob Pike <r@golang.org>
Diffstat (limited to 'src/cmd/doc')
-rw-r--r-- | src/cmd/doc/doc_test.go | 31 | ||||
-rw-r--r-- | src/cmd/doc/pkg.go | 12 | ||||
-rw-r--r-- | 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 +} |