cmg/go doc: flag -short

Konstantin8105 commented 4 years ago

What version of Go are you using (`go version`)?

$ go version
go version go1.14.1 linux/amd64

Does this issue reproduce with the latest release?

Yes

What operating system and processor architecture are you using (`go env`)?

go env Output

$ go env
GO111MODULE=""
GOARCH="amd64"
GOBIN=""
GOCACHE="/home/konstantin/.cache/go-build"
GOENV="/home/konstantin/.config/go/env"
GOEXE=""
GOFLAGS=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOINSECURE=""
GONOPROXY=""
GONOSUMDB=""
GOOS="linux"
GOPATH="/home/konstantin/go"
GOPRIVATE=""
GOPROXY="https://proxy.golang.org,direct"
GOROOT="/usr/local/go"
GOSUMDB="sum.golang.org"
GOTMPDIR=""
GOTOOLDIR="/usr/local/go/pkg/tool/linux_amd64"
GCCGO="gccgo"
AR="ar"
CC="gcc"
CXX="g++"
CGO_ENABLED="1"
GOMOD=""
CGO_CFLAGS="-g -O2"
CGO_CPPFLAGS=""
CGO_CXXFLAGS="-g -O2"
CGO_FFLAGS="-g -O2"
CGO_LDFLAGS="-g -O2"
PKG_CONFIG="pkg-config"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build047862315=/tmp/go-build -gno-record-gcc-switches"

What did you do?

Run go doc with flag -short and in according to documentation:

$ go doc -h
...
  -short
        one-line representation for each symbol
...

Representation in one-line, but not without full list of constants.

What did you expect to see?

$ go doc -short math
const E   = 2.71828182845904523536028747135266249775724709369995957496696763 // https://oeis.org/A001113
const Pi  = 3.14159265358979323846264338327950288419716939937510582097494459 // https://oeis.org/A000796
const Phi = 1.61803398874989484820458683436563811772030917980576286213544862 // https://oeis.org/A001622
const Sqrt2   = 1.41421356237309504880168872420969807856967187537694807317667974 // https://oeis.org/A002193
const SqrtE   = 1.64872127070012814684865078781416357165377610071014801157507931 // https://oeis.org/A019774
const SqrtPi  = 1.77245385090551602729816748334114518279754945612238712821380779 // https://oeis.org/A002161
const SqrtPhi = 1.27201964951406896425242246173749149171560804184009624861664038 // https://oeis.org/A139339
const Ln2    = 0.693147180559945309417232121458176568075500134360255254120680009 // https://oeis.org/A002162
const Log2E  = 1 / Ln2
const Ln10   = 2.30258509299404568401799145468436420760110148862877297603332790 // https://oeis.org/A002392
const Log10E = 1 / Ln10
func Abs(x float64) float64
func Acos(x float64) float64

What did you see instead?

$ go doc -short math
const E = 2.71828182845904523536028747135266249775724709369995957496696763 ...
const MaxFloat32 = 3.40282346638528859811704183484516925440e+38 ...
const MaxInt8 = 1<<7 - 1 ...
func Abs(x float64) float64
func Acos(x float64) float64

robpike commented 4 years ago

Taken out of context, this does seem odd, but the rest of the documentation clarifies what symbols are printed. In particular, it says right up top, "a const", not all consts, and "the item" not all items.

I think the real problem here is to discover a better way to show all the constants in a declaration. The "-short" flag is surely not it, but it's not clear what, if anything, should be changed.

Konstantin8105 commented 4 years ago

Excuse me, agree.	Command	Functions	Structs	Struct methods
`go doc -all math`	yes	yes	yes	yes
`go doc math`	yes	yes	none	short
`go doc -short math`	yes	yes	none	short

golang / go