Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

x/tools/cmd/godoc: generate docs for test files #17509

Closed
rpetersen76 opened this issue Oct 18, 2016 · 1 comment
Closed

x/tools/cmd/godoc: generate docs for test files #17509

rpetersen76 opened this issue Oct 18, 2016 · 1 comment
Labels
FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone
Go1.10

Comments

@rpetersen76
Copy link

Please answer these questions before submitting your issue. Thanks!

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

go1.7 linux/amd64

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

GOARCH="amd64"
GOBIN=""
GOEXE=""
GOHOSTARCH="amd64"
GOHOSTOS="linux"
GOOS="linux"
GOPATH="/projects/ntsw-sw19/home/ryanp/ngsdk/INTERNAL/appl/regress/go"
GORACE=""
GOROOT="/projects/ntsw-tools/go"
GOTOOLDIR="/projects/ntsw-tools/go/pkg/tool/linux_amd64"
CC="gcc"
GOGCCFLAGS="-fPIC -m64 -pthread -fmessage-length=0 -fdebug-prefix-map=/tmp/go-build767044606=/tmp/go-build -gno-record-gcc-switches"
CXX="g++"
CGO_ENABLED="1"

What did you do?

Trying to run godoc on a directory with test files (_test.go) does not produce documentation.

It would be great if a -test flag could be added to include generating documentation for packages that contain test files.
@quentinmit quentinmit changed the title godoc needs support for generating docs for test files cmd/doc: generate docs for test files Oct 20, 2016
@quentinmit quentinmit added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Oct 20, 2016
@quentinmit quentinmit added this to the Go1.9Maybe milestone Oct 20, 2016
@bradfitz bradfitz modified the milestones: Go1.10, Go1.9Maybe Jun 28, 2017
@bradfitz bradfitz changed the title cmd/doc: generate docs for test files x/tools/cmd/godoc: generate docs for test files Jun 28, 2017
@rsc
Copy link
Contributor

rsc commented Dec 4, 2017

Godoc is about showing the exported API from a package. Test files are not part of the exported API.

If the tests are so complex that they need documentation to find out how to use them, they're also often worth using from multiple tests, in which case we typically move them into separate standalone packages (not in *_test.go files), like testing/iotest and net/http/httptest. That might be the right solution for your case as well.

@rsc rsc closed this as completed Dec 4, 2017
@golang golang locked and limited conversation to collaborators Dec 4, 2018
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Milestone
Go1.10
Development

No branches or pull requests
5 participants
@bradfitz @rsc @quentinmit @gopherbot @rpetersen76