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

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

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

cmd/doc: handle embedded fields properly

2016-02-22T23:40:02+00:00

The structure of the code meant that an embedded field was never
checked for export status. We need to check the name of the type,
which is either of type T or type *T, and T might be unexported.

Fixes #14356.

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

cmd/doc: fix strange indentation artifacts with unexported fields

2015-11-17T20:51:19+00:00

The NamePos value was not being set, and would default to a value
of zero. This would cause the printing logic to get confused as
to where exactly to place the "Has unexported fields" string.

A trivial package changes from

<
type A struct {
	A int // A
	B int
			// B
	// Has unexported fields.
}
>

to

<
type A struct {
	A int // A
	B int // B
	// Has unexported fields.
}
>

Fixes #12971

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

cmd/doc: don't drop const/var block if first entry is unexported

2015-09-21T16:42:09+00:00

The code assumed that if the first entry was unexported, all the
entries were. The fix is simple: delete a bunch of code.

Fixes #12286.

Change-Id: Icb09274e99ce97df4d8bddbe59d17a5c0622e4c6
Reviewed-on: https://go-review.googlesource.com/14780
Reviewed-by: Andrew Gerrand

cmd/doc: fix copy/paste error in test

2015-06-22T22:29:35+00:00

Some of those consts were supposed to be vars.

Caught by Ingo Oeser.

Change-Id: Ifc12e4a8ee61ebf5174e4ad923956c546dc096e2
Reviewed-on: https://go-review.googlesource.com/11296
Reviewed-by: Andrew Gerrand

cmd/doc: add test for constructor, fix build

2015-06-20T10:35:38+00:00

Most important: skip test on darwin/arm64 for unclear reasons.

First cut at the test missed this feature of go doc: when asking for
the docs for a type, include any function that looks like it constructs
a that type as a return value.

Change-Id: I124e7695e5d365e2b12524b541a9a4e6e0300fbc
Reviewed-on: https://go-review.googlesource.com/11295
Reviewed-by: Rob Pike