delta/go-git.git/src/cmd/doc/testdata, branch dev.cmdgo

cmd/doc: properly display interface methods

2021-03-19T03:05:26+00:00

Previously, we used to call doc.ToText to print each comment
in a comment group attached to an interface method. This broke any
preformatted code block attached to the comment, and displayed everything
aligned to a single column. Additionally, the name of the interface
also wasn't displayed which didn't show which interface
the method belonged to.

To fix this, we print the entire interface node using format.Node
which takes care of displaying the comments correctly, and we also
filter out the methods that don't match, so that the method can be
displayed as belonging to an interface.

As an example, previously it would show:

// Comment before exported method.
//
// // Code block showing how to use ExportedMethod
// func DoSomething() error {
// ExportedMethod()
// return nil
// }
func ExportedMethod()  // Comment on line with exported method.

Now, it shows:

type ExportedInterface interface {
	// Comment before exported method.
	//
	//	// Code block showing how to use ExportedMethod
	//	func DoSomething() error {
	//		ExportedMethod()
	//		return nil
	//	}
	ExportedMethod() // Comment on line with exported method.

}

Fixes #43188

Change-Id: I28099fe4aab35e08049b2616a3506240f57133cc
Reviewed-on: https://go-review.googlesource.com/c/go/+/279433
Trust: Agniva De Sarker 
Trust: Daniel Martí 
Reviewed-by: Rob Pike

cmd/doc: fix merging comments in -src mode

2020-03-05T03:55:11+00:00

These changes fix go doc -src mode that vomits comments from random files if
filesystem does not sort files by name. The issue was with parse.ParseDir
using the Readdir order of files, which varies between platforms and filesystem
implementations. Another option is to merge comments using token.FileSet.Iterate
order in cmd/doc, but since ParseDir is mostly used in go doc, I’ve opted for
smaller change because it’s unlikely to break other uses or cause any perfomance
issues.

Example (macOS APFS): `go doc -src net.ListenPacket`

Change-Id: I7f9f368c7d9ccd9a2cbc48665f2cb9798c7b3a3f
GitHub-Last-Rev: 654fb450421266a0bb64518016944db22bd681e3
GitHub-Pull-Request: golang/go#36104
Reviewed-on: https://go-review.googlesource.com/c/go/+/210999
Run-TryBot: Rob Pike 
TryBot-Result: Gobot Gobot 
Reviewed-by: Rob Pike

cmd/doc: show the package clause always

2019-11-12T05:24:00+00:00

If no writes to the package buffer happen, then the package clause
does not get printed. This is a bug for cases where a file just contains
the package clause.

We fix this by separating the printing of package clause to a new
function and calling it from (*pkgBuffer).Write as well as (*Package).flush.

Updates #31457

Change-Id: Ia3bd0ea3963274c460a45d1e37fafc6ee0a197f0
Reviewed-on: https://go-review.googlesource.com/c/go/+/206128
Run-TryBot: Agniva De Sarker 
TryBot-Result: Gobot Gobot 
Reviewed-by: Rob Pike

cmd/doc: show variables of unexported types for -all

2019-11-12T04:09:39+00:00

We use the typedValue map to prevent showing typed variables
and constants from appearing in the VARIABLES/CONSTANTS section
because they will be anyways shown in the TYPES section
for that type.

However, when a type is unexported, but the variable is exported,
then unconditionally setting it to true in the map suppresses it
from being shown in the VARIABLES section. Thus, we set the
variable or constant in the typedValue map only when
the type name is exported.

Fixes #31067

Change-Id: Id3ec4b313c9ea7e3ce6fe279680d56f65451719f
Reviewed-on: https://go-review.googlesource.com/c/go/+/206129
Run-TryBot: Agniva De Sarker 
Reviewed-by: Rob Pike 
TryBot-Result: Gobot Gobot

cmd/doc: correctly indent pre-formatted blocks

2019-03-31T23:35:35+00:00

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

cmd/doc: add a line gap after a method with no comment

2019-03-08T07:12:55+00:00

Fixes #30492

Change-Id: Iec658bdf8bfac21e1bcc3eed900722cc535ec00a
Reviewed-on: https://go-review.googlesource.com/c/go/+/166178
Run-TryBot: Agniva De Sarker 
TryBot-Result: Gobot Gobot 
Reviewed-by: Rob Pike

cmd/doc: add a -src flag to show original source

2018-10-10T23:40:35+00:00

It's long-desired but was blocked by #26835. That is now fixed, so
it's easy. When -src is off, we behave as before. But with -src
set, initialize the go/doc package to preserve the original AST and
things flow very easily.

With -src, since you're seeing inside the package source anyway it
shows unexported fields and constants: you see the original source.
But you still need -u to ask about them.

Fixes #18807

Change-Id: I473e90323b4eff0735360274dc0d2d9dba16ff8b
Reviewed-on: https://go-review.googlesource.com/c/140959
Reviewed-by: Andrew Gerrand 
Run-TryBot: Andrew Gerrand 
TryBot-Result: Gobot Gobot

cmd/doc: continue to search when package import fails

2018-06-11T22:09:14+00:00

Keep searching for a package that is both findable and importable. The
current code would always guarantee that a package was findable but
exited if it was not importable.

Fixes #25478

Change-Id: I237b7dfafb930cae02538c4a2e4d5ce0c1058478
Reviewed-on: https://go-review.googlesource.com/114295
Reviewed-by: Bryan C. Mills 
Reviewed-by: Rob Pike 
Run-TryBot: Bryan C. Mills 
TryBot-Result: Gobot Gobot

cmd/doc: suppress the error message for *package.ident embedded in struct type

2017-12-20T19:05:19+00:00

The current implementation prints a log, "invalid program: unexpected
type for embedded field", when the form *package.ident is embedded in
a struct declaration.

Note that since valid qualified identifiers must be exported, the result
for a valid program does not change.

Change-Id: If8b9d7056c56b6a6c5482eb749168a63c65ef685
Reviewed-on: https://go-review.googlesource.com/84436
Reviewed-by: Robert Griesemer 
Run-TryBot: Robert Griesemer 
TryBot-Result: Gobot Gobot

cmd/doc: don't print a declaration twice

2017-11-20T05:08:37+00:00

That can occur if we have -u set and there is an upper- and lower-case
name of the same spelling in a single declaration.

A rare corner case but easy to fix.

Fix by remembering what we've printed.

Fixes #21797.

Change-Id: Ie0b681ae8c277fa16e9635ba594c1dff272b8aeb
Reviewed-on: https://go-review.googlesource.com/78715
Reviewed-by: Brad Fitzpatrick 
Run-TryBot: Brad Fitzpatrick 
TryBot-Result: Gobot Gobot