Stowage/go
2
0
Fork 0
mirror of https://github.com/golang/go.git synced 2025-12-08 06:10:04 +00:00
Code Issues Projects Releases Packages Wiki Activity

cmd/doc: ensure summaries truly are only one line

Browse source 
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 <thebrokentoaster@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
Reviewed-by: Rob Pike <r@golang.org>
This commit is contained in:
Joe Tsai 2016-08-03 00:31:17 -07:00 • committed by Joe Tsai
parent 44009a2413
commit 84743c348b
3 changed files with 224 additions and 77 deletions
Download patch file Download diff file Expand all files Collapse all files

30
src/cmd/doc/doc_test.go
View file

@ -55,19 +55,22 @@ var tests = []test{
[]string{p},
[]string{
`Package comment`,
`const ExportedConstant = 1`, // Simple constant.
`const ConstOne = 1`, // First entry in constant block.
`const ConstFive ...`, // From block starting with unexported constant.
`var ExportedVariable = 1`, // Simple variable.
`var VarOne = 1`, // First entry in variable block.
`func ExportedFunc\(a int\) bool`, // Function.
`func ReturnUnexported\(\) unexportedType`, // Function with unexported return type.
`type ExportedType struct { ... }`, // Exported type.
`const ExportedTypedConstant ExportedType = iota`, // Typed constant.
`const ExportedTypedConstant_unexported unexportedType`, // Typed constant, exported for unexported type.
`const ConstLeft2 uint64 ...`, // Typed constant using unexported iota.
`const ConstGroup1 unexportedType = iota ...`, // Typed constant using unexported type.
`const ConstGroup4 ExportedType = ExportedType{}`, // Typed constant using exported type.
`const ExportedConstant = 1`, // Simple constant.
`const ConstOne = 1`, // First entry in constant block.
`const ConstFive ...`, // From block starting with unexported constant.
`var ExportedVariable = 1`, // Simple variable.
`var VarOne = 1`, // First entry in variable block.
`func ExportedFunc\(a int\) bool`, // Function.
`func ReturnUnexported\(\) unexportedType`, // Function with unexported return type.
`type ExportedType struct{ ... }`, // Exported type.
`const ExportedTypedConstant ExportedType = iota`, // Typed constant.
`const ExportedTypedConstant_unexported unexportedType`, // Typed constant, exported for unexported type.
`const ConstLeft2 uint64 ...`, // Typed constant using unexported iota.
`const ConstGroup1 unexportedType = iota ...`, // Typed constant using unexported type.
`const ConstGroup4 ExportedType = ExportedType{}`, // Typed constant using exported type.
`const MultiLineConst = ...`, // Multi line constant.
`var MultiLineVar = map\[struct{ ... }\]struct{ ... }{ ... }`, // Multi line variable.
`func MultiLineFunc\(x interface{ ... }\) \(r struct{ ... }\)`, // Multi line function.
},
[]string{
`const internalConstant = 2`, // No internal constants.
@ -102,6 +105,7 @@ var tests = []test{
`Comment about exported constant`, // No comment for simple constant.
`Comment about block of constants`, // No comment for constant block.
`Comment about internal function`, // No comment for internal function.
`MultiLine(String|Method|Field)`, // No data from multi line portions.
},
},