Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

cmd/doc: indents pre-formatted documentation in functions badly #29708

Closed
segevfiner opened this issue Jan 12, 2019 · 3 comments
Closed

cmd/doc: indents pre-formatted documentation in functions badly #29708

segevfiner opened this issue Jan 12, 2019 · 3 comments
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.

Comments

@segevfiner
Copy link
Contributor

What version of Go are you using (go version)?

$ go version
go version go1.11.4 windows/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (go env)?

go env Output
$ go env
set GOARCH=amd64
set GOBIN=
set GOCACHE=<snip>\AppData\Local\go-build
set GOEXE=.exe
set GOFLAGS=
set GOHOSTARCH=amd64
set GOHOSTOS=windows
set GOOS=windows
set GOPATH=<snip>\go
set GOPROXY=
set GORACE=
set GOROOT=<snip>\go
set GOTMPDIR=
set GOTOOLDIR=<snip>\go\pkg\tool\windows_amd64
set GCCGO=gccgo
set CC=gcc
set CXX=g++
set CGO_ENABLED=1
set GOMOD=
set CGO_CFLAGS=-g -O2
set CGO_CPPFLAGS=
set CGO_CXXFLAGS=-g -O2
set CGO_FFLAGS=-g -O2
set CGO_LDFLAGS=-g -O2
set PKG_CONFIG=pkg-config
set GOGCCFLAGS=-m64 -mthreads -fno-caret-diagnostics -Qunused-arguments -fmessage-length=0 -fdebug-prefix-map=<snip>\AppData\Local\Temp\go-build819611282=/tmp/go-build -gno-record-gcc-switches

What did you do?

  1. Save this file as $GOPATH/hello/hello.go:
/*
Package hello prints "Hello, World!".

Usage

	hello.Hello()
*/
package hello

import "fmt"

// Hello prints "Hello, World!"
//
// Usage
//
//     hello.Hello()
func Hello() {
	fmt.Println("Hello, World!")
}
  1. Run:
C:\>go doc hello
package hello // import "hello"

Package hello prints "Hello, World!".

Usage

    hello.Hello()

func Hello()

C:\>go doc hello.Hello
func Hello()
    Hello prints "Hello, World!"

    Usage

    hello.Hello()

What did you expect to see?

I expect the second command output to be:

C:\>go doc hello.Hello
func Hello()
    Hello prints "Hello, World!"

    Usage

        hello.Hello()

What did you see instead?

The pre-formatted line is indented the same as a normal paragraph.

Analysis

This is due to the indent/preIndent arguments used in src/cmd/doc/pkg.go

Note that the signature is as follows:

func ToText(w io.Writer, text string, indent, preIndent string, width int)

indent is before preIndent! it's possible it's mixed up a bit currently in the code, but still given the desired results. Note that editor extensions like vscode-go are already parsing the output of go doc depending on it's indentation behavior.

In function doc, which is already indented, preIndent should be indented with 8 spaces instead of 4 so that it stands out as expected.
@segevfiner segevfiner changed the title go doc indents outputted documetation badly go doc indents outputted pre-formatted documetation badly in functions Jan 12, 2019
@segevfiner segevfiner changed the title go doc indents outputted pre-formatted documetation badly in functions go doc indents pre-formatted documetation badly in functions Jan 12, 2019
@segevfiner segevfiner changed the title go doc indents pre-formatted documetation badly in functions go doc indents pre-formatted documetation in functions badly Jan 12, 2019
@segevfiner segevfiner mentioned this issue Jan 12, 2019
Closed
@agnivade agnivade changed the title go doc indents pre-formatted documetation in functions badly cmd/doc: indents pre-formatted documentation in functions badly Jan 13, 2019
@agnivade agnivade added the NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one. label Jan 13, 2019
@agnivade
Copy link
Contributor

/cc @robpike

@segevfiner segevfiner mentioned this issue Jan 13, 2019
Closed
7 tasks
@agnivade
Copy link
Contributor

The behavior seems to have been always like this.

For package docs, the indent is "" and preIndent is indent, which indents pre-formatted code. But for method docs, both indent and preIndent are indent. So everything is at the same level.

Seems to me an inconsistency we should fix. But I wonder if there is some historical reason for this. @robpike ?

segevfiner added a commit to segevfiner/go that referenced this issue Mar 28, 2019
@segevfiner
cmd/doc: correctly indent pre-formatted blocks
cd9b03c 
They were previously indented at the same level as the normaal text when
printing a single symbol or the description of a field.

Try:
* go doc text/template Must
* go doc http Request.Header

Fixes golang#29708
segevfiner added a commit to segevfiner/go that referenced this issue Mar 28, 2019
@segevfiner
cmd/doc: correctly indent pre-formatted blocks
e5c86a3 
They were previously indented at the same level as the normal text when
printing a single symbol or the description of a field.

Try:
* go doc text/template Must
* go doc http Request.Header

Fixes golang#29708
@segevfiner segevfiner mentioned this issue Mar 28, 2019
Closed
@gopherbot
Copy link

Change https://golang.org/cl/169957 mentions this issue: cmd/doc: correctly indent pre-formatted blocks

segevfiner added a commit to segevfiner/go that referenced this issue Mar 28, 2019
@segevfiner
cmd/doc: correctly indent pre-formatted blocks
ea3bdc2 
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 golang#29708
segevfiner added a commit to segevfiner/go that referenced this issue Mar 28, 2019
@segevfiner
cmd/doc: correctly indent pre-formatted blocks
e3208c6 
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 golang#29708
segevfiner added a commit to segevfiner/go that referenced this issue Mar 29, 2019
@segevfiner
cmd/doc: correctly indent pre-formatted blocks
439c0fe 
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 golang#29708
@golang golang locked and limited conversation to collaborators Mar 30, 2020
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsInvestigation Someone must examine and confirm this is a valid issue and not a duplicate of an existing one.
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@agnivade @gopherbot @segevfiner