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

go/doc: Examples includes example functions with returns #36185

Open
dmitshur opened this issue Dec 17, 2019 · 5 comments
Open

go/doc: Examples includes example functions with returns #36185

dmitshur opened this issue Dec 17, 2019 · 5 comments
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Milestone

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Dec 17, 2019

As documented at https://golang.org/pkg/testing#hdr-Examples, an example function is expected to have no parameters and no returns. doc.Examples considers functions with parameters as invalid examples and skips them.

Unlike the vet pass, doc.Examples does not check if there are results.

That means both of these are recognized as examples by doc.Examples:

func ExampleHello() {
	fmt.Println("hello")
	// Output: hello
}

func ExampleHi() int {
	fmt.Println("hi")
	return 42
	// Output: hi
}

It means x/tools/cmd/godoc and other tools that display documentation may show such invalid examples:

godoc screenshot

image

go vet catches this problem:

# example.org/p
./style_test.go:131:1: ExampleHi should return nothing

Perhaps doc.Examples should be changed to treat functions with returns as invalid examples, like it does for functions with parameters, and not include them in its output.

/cc @griesemer @jayconrod @matloob @bcmills

(This is somewhat related to issue #36184 and CL 211598.)

@dmitshur dmitshur added the NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made. label Dec 17, 2019
@dmitshur dmitshur added this to the Backlog milestone Dec 17, 2019
@jayconrod
Copy link
Contributor

Part of the reasoning in CL 211598 was that go/doc.Examples should return the set of example functions that go test will call. If go test filtered anything out, then go/doc.Examples would be returning something inaccurate.

Are examples with return values ignored or rejected by go test? I suspect they're called. Since testing says they should not have return values and go vet rejects them, this seems like a bug.

@dmitshur
Copy link
Contributor Author

dmitshur commented Dec 17, 2019

go test fails to build the test package when an example function returns something:

$ go test 
# example.com/p
/tmp/go-build839897815/b001/_testmain.go:44:21: cannot use p.ExampleHi (type func() int) as type func() in field value
FAIL	example.com/p [build failed]

Note that I expect changing doc.Examples to skip such examples will cause go test to skip ExampleHi and succeed, because as I understand, go test indirectly relies on doc.Examples to find runnable examples.

@dmitshur
Copy link
Contributor Author

Proposal #21111 (which is on hold for error handling) is related.

@matloob
Copy link
Contributor

matloob commented Dec 23, 2019

I think we should remove them, and let the vet check flag them.

@michael-schaller
Copy link
Contributor

I think we should go ahead with proposal #21111 and allow Examples to return an error.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
NeedsDecision Feedback is required from experts, contributors, and/or the community before a change can be made.
Projects
None yet
Development

No branches or pull requests

4 participants