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

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

cmd/doc: group constructors with type in package presentation

2016-04-21T21:45:05+00:00

Fixes #14004.

$ go doc encoding.gob
Before:
func Register(value interface{})
func RegisterName(name string, value interface{})
func NewDecoder(r io.Reader) *Decoder
func NewEncoder(w io.Writer) *Encoder
type CommonType struct { ... }
type Decoder struct { ... }
type Encoder struct { ... }
type GobDecoder interface { ... }
type GobEncoder interface { ... }

After:
func Register(value interface{})
func RegisterName(name string, value interface{})
type CommonType struct { ... }
type Decoder struct { ... }
    func NewDecoder(r io.Reader) *Decoder
type Encoder struct { ... }
    func NewEncoder(w io.Writer) *Encoder
type GobDecoder interface { ... }
type GobEncoder interface { ... }

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

all: delete dead non-test code

2016-03-25T06:28:13+00:00

This change removes a lot of dead code. Some of the code has never been
used, not even when it was first commited. The rest shouldn't have
survived refactors.

This change doesn't remove unused routines helpful for debugging, nor
does it remove code that's used in commented out blocks of code that are
only unused temporarily. Furthermore, unused constants weren't removed
when they were part of a set of constants from specifications.

One noteworthy omission from this CL are about 1000 lines of unused code
in cmd/fix, 700 lines of which are the typechecker, which hasn't been
used ever since the pre-Go 1 fixes have been removed. I wasn't sure if
this code should stick around for future uses of cmd/fix or be culled as
well.

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

all: delete dead test code

2016-03-21T07:10:08+00:00

This deletes unused code and helpers from tests.

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

all: make copyright headers consistent with one space after period

2016-03-01T23:34:33+00:00

This is a subset of https://golang.org/cl/20022 with only the copyright
header lines, so the next CL will be smaller and more reviewable.

Go policy has been single space after periods in comments for some time.

The copyright header template at:

    https://golang.org/doc/contribute.html#copyright

also uses a single space.

Make them all consistent.

Change-Id: Icc26c6b8495c3820da6b171ca96a74701b4a01b0
Reviewed-on: https://go-review.googlesource.com/20111
Run-TryBot: Brad Fitzpatrick 
Reviewed-by: Ian Lance Taylor 
Reviewed-by: Matthew Dempsky 
TryBot-Result: Gobot Gobot