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

cmd/doc: print Go syntax when printing struct.field docs

2017-07-06T21:57:52+00:00

Fixes #20928

Change-Id: I7f7aafb8ff4b5deb50c286a9ae81c34ee85e56a9
Reviewed-on: https://go-review.googlesource.com/47730
Reviewed-by: Rob Pike 
Run-TryBot: Brad Fitzpatrick 
TryBot-Result: Gobot Gobot

cmd/doc: implement "go doc struct.field"

2017-03-22T05:37:50+00:00

By analogy with the handling of methods on types, show the documentation
for a single field of a struct.

	% go doc ast.structtype.fields
	struct StructType {
	    Fields *FieldList  // list of field declarations
	}
	%

Fixes #19169.

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

cmd/doc: truncate long lists of arguments

2017-02-24T10:52:50+00:00

Some field-lists (especially in generated code) can be excessively long.
In the one-line printout, it does not make sense to print all elements
of the list if line-wrapping causes the "one-line" to become multi-line.

// Before:
var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", "someArgument5", "someArgument6", "someArgument7", "someArgument8")

// After:
var LongLine = newLongLine("someArgument1", "someArgument2", "someArgument3", "someArgument4", ...)

Change-Id: I4bbbe2dbd1d7be9f02d63431d213088c3dee332c
Reviewed-on: https://go-review.googlesource.com/36031
Run-TryBot: Joe Tsai 
TryBot-Result: Gobot Gobot 
Reviewed-by: Rob Pike

[dev.typealias] cmd/doc: update for type alias

2017-01-25T17:27:07+00:00

For #18130.

Change-Id: I06b05a2b45a2aa6764053fc51e05883063572dad
Reviewed-on: https://go-review.googlesource.com/35670
Run-TryBot: Russ Cox 
Reviewed-by: Robert Griesemer

cmd/doc: show documentation for interface methods when requested explicitly

2016-10-25T20:09:49+00:00

For historical reasons, the go/doc package does not include
the methods within an interface as part of the documented
methods for that type. Thus,

	go doc ast.Node.Pos

gives an incorrect and confusing error message:

	doc: no method Node.Pos in package go/ast

This CL does some dirty work to dig down to the methods
so interface methods now present their documentation:

% go doc ast.node.pos
func Pos() token.Pos  // position of first character belonging to the node
%

It must largely sidestep the doc package to do this, which
is a shame. Perhaps things will improve there one day.

The change does not handle embeddings, and in principle the
same approach could be done for struct fields, but that is also
not here yet. But this CL fixes the thing that was bugging me.

Change-Id: Ic10a91936da96f54ee0b2f4a4fe4a8c9b93a5b4a
Reviewed-on: https://go-review.googlesource.com/31852
Reviewed-by: Robert Griesemer

cmd/doc: continue searching after error reading directory

2016-10-24T15:25:33+00:00

If a directory in GOPATH is unreadable, we should keep looking for other
packages. Otherwise we can give the misleading error "no buildable Go
source files".

Fixes #16240

Change-Id: I38e1037f56ec463d3c141f0508fb74211cb90f13
Reviewed-on: https://go-review.googlesource.com/31713
Run-TryBot: Quentin Smith 
TryBot-Result: Gobot Gobot 
Reviewed-by: Russ Cox 
Reviewed-by: Rob Pike

cmd/doc: ensure summaries truly are only one line

2016-10-05T00:12:35+00:00

The documentation for doc says:
> Doc prints the documentation comments associated with the item identified by its
> arguments (a package, const, func, type, var, or method) followed by a one-line
> summary of each of the first-level items "under" that item (package-level
> declarations for a package, methods for a type, etc.).

Certain variables (and constants, functions, and types) have value specifications
that are multiple lines long. Prior to this change, doc would print out all of the
lines necessary to display the value. This is inconsistent with the documented
behavior, which guarantees a one-line summary for all first-level items.
We fix this here by writing a general oneLineNode method that always returns
a one-line summary (guaranteed!) of any input node.

Packages like image/color/palette and unicode now become much
more readable since large slices are now a single line.

$ go doc image/color/palette
<<<
// Before:
var Plan9 = []color.Color{
	color.RGBA{0x00, 0x00, 0x00, 0xff},
	color.RGBA{0x00, 0x00, 0x44, 0xff},
	color.RGBA{0x00, 0x00, 0x88, 0xff},
	... // Hundreds of more lines!
}
var WebSafe = []color.Color{
	color.RGBA{0x00, 0x00, 0x00, 0xff},
	color.RGBA{0x00, 0x00, 0x33, 0xff},
	color.RGBA{0x00, 0x00, 0x66, 0xff},
	... // Hundreds of more lines!
}

// After:
var Plan9 = []color.Color{ ... }
var WebSafe = []color.Color{ ... }
>>>

In order to test this, I ran `go doc` and `go doc -u` on all of the
standard library packages and diff'd the output with and without the
change to ensure that all differences were intended.

Fixes #13072

Change-Id: Ida10b7796b7e4e174a929b55c60813a9eb7158fe
Reviewed-on: https://go-review.googlesource.com/25420
Run-TryBot: Joe Tsai 
TryBot-Result: Gobot Gobot 
Reviewed-by: Rob Pike

cmd/doc: perform type grouping for constants and variables

2016-09-30T23:40:48+00:00

In golang.org/cl/22354, we added functionality to group functions under the
type that they construct to. In this CL, we extend the same concept to
constants and variables. This makes the doc tool more consistent with what
the godoc website does.

$ go doc reflect | egrep "ChanDir|Kind|SelectDir"
<<<
// Before:
const RecvDir ChanDir = 1 << iota ...
const Invalid Kind = iota ...
type ChanDir int
type Kind uint
type SelectDir int
    func ChanOf(dir ChanDir, t Type) Type

// After:
type ChanDir int
    const RecvDir ChanDir = 1 << iota ...
type Kind uint
    const Invalid Kind = iota ...
type SelectDir int
    const SelectSend SelectDir ...
    func ChanOf(dir ChanDir, t Type) Type
>>>

Furthermore, a fix was made to ensure that the type was printed in constant
blocks when the iota was applied on an unexported field.

$ go doc reflect SelectSend
<<<
// Before:
const (
	SelectSend    // case Chan <- Send
	SelectRecv    // case <-Chan:
	SelectDefault // default
)

// After:
const (
	SelectSend    SelectDir // case Chan <- Send
	SelectRecv              // case <-Chan:
	SelectDefault           // default
)
>>>

Fixes #16569

Change-Id: I26124c3d19e50caf9742bb936803a665e0fa6512
Reviewed-on: https://go-review.googlesource.com/25419
Reviewed-by: Rob Pike 
Run-TryBot: Joe Tsai 
TryBot-Result: Gobot Gobot

cmd/doc: ensure functions with unexported return values are shown

2016-08-02T03:24:48+00:00

The commit in golang.org/cl/22354 groups constructors functions under
the type that they construct to. However, this caused a minor regression
where functions that had unexported return values were not being printed
at all. Thus, we forgo the grouping logic if the type the constructor falls
under is not going to be printed.

Fixes #16568

Change-Id: Idc14f5d03770282a519dc22187646bda676af612
Reviewed-on: https://go-review.googlesource.com/25369
Run-TryBot: Joe Tsai 
Reviewed-by: Rob Pike 
TryBot-Result: Gobot Gobot

cmd/doc: handle embedded interfaces properly

2016-08-02T01:58:14+00:00

Changes made:
* Disallow star expression on interfaces as this is not possible.
* Show an embedded "error" in an interface as public similar to
how godoc does it.
* Properly handle selector expressions in both structs and interfaces.
This is possible since a type may refer to something defined in
another package (e.g. io.Reader).

Before:
<<<
$ go doc runtime.Error
type Error interface {

    // RuntimeError is a no-op function but
    // serves to distinguish types that are run time
    // errors from ordinary errors: a type is a
    // run time error if it has a RuntimeError method.
    RuntimeError()
    // Has unexported methods.
}

$ go doc compress/flate Reader
doc: invalid program: unexpected type for embedded field
doc: invalid program: unexpected type for embedded field
type Reader interface {
    io.Reader
    io.ByteReader
}
>>>

After:
<<<
$ go doc runtime.Error
type Error interface {
    error

    // RuntimeError is a no-op function but
    // serves to distinguish types that are run time
    // errors from ordinary errors: a type is a
    // run time error if it has a RuntimeError method.
    RuntimeError()
}

$ go doc compress/flate Reader
type Reader interface {
    io.Reader
    io.ByteReader
}
>>>

Fixes #16567

Change-Id: I272dede971eee9f43173966233eb8810e4a8c907
Reviewed-on: https://go-review.googlesource.com/25365
Reviewed-by: Rob Pike 
Run-TryBot: Joe Tsai 
TryBot-Result: Gobot Gobot