Skip to content

go/doc: whole file is used as example even when there are tests or benchmarks #38409

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.

Sign up for GitHub

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
Closed
dmitshur opened this issue Apr 13, 2020 · 6 comments
Closed

go/doc: whole file is used as example even when there are tests or benchmarks #38409

dmitshur opened this issue Apr 13, 2020 · 6 comments
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Milestone
Go1.15

Comments

@dmitshur
Copy link
Contributor

dmitshur commented Apr 13, 2020 •
edited
Loading

Package testing says:

The entire test file is presented as the example when it contains a single example function, at least one other function, type, variable, or constant declaration, and no test or benchmark functions.

This program produces expected results in Go 1.13:

$ go1.13.10 run .
errors.As has a whole file example: false

It stopped working in Go 1.14:

$ go1.14.2 run .      
errors.As has a whole file example: true

This is because CL 211357 added an early continue when the function being considered has parameters. The intention was to skip Example functions with parameters. However, the skip happens too early, before this check:

if isTest(name, "Test") || isTest(name, "Benchmark") {
	hasTests = true
	continue
}

Tests and benchmarks always have 1 parameter, so hasTests never has a chance to get set to true.

/cc @jayconrod @matloob
@dmitshur dmitshur added the NeedsFix The path to resolution is known, but the work has not been done. label Apr 13, 2020
@dmitshur dmitshur added this to the Go1.15 milestone Apr 13, 2020
@dmitshur dmitshur mentioned this issue Apr 13, 2020
Closed
@dmitshur dmitshur changed the title go/doc: while file is used as example even when there are tests or benchmarks go/doc: whole file is used as example even when there are tests or benchmarks Apr 13, 2020
@dmitshur dmitshur mentioned this issue Apr 13, 2020
Closed
@posener
Copy link

posener commented Apr 13, 2020

Thanks for finding the bug!
If I understand the github milestone correctly, the examples in the doc will remain broken in 1.14?

@FiloSottile
Copy link
Contributor

@gopherbot please open a backport issue for 1.14.

This is a regression that impacts user visible documentations, without a workaround on the doc generation side (as opposed to modifying the target source, which might be an existing version or third-party).

@gopherbot gopherbot mentioned this issue Apr 13, 2020
Closed
@gopherbot
Copy link
Contributor

Backport issue(s) opened: #38418 (for 1.14).

Remember to create the cherry-pick CL(s) as soon as the patch is submitted to master, according to https://golang.org/wiki/MinorReleases.

@dmitshur dmitshur self-assigned this Apr 17, 2020
@dmitshur
Copy link
Contributor Author

Fixed by CL 222477 (PR #37730), thank you @flyingmutant.

/cc @griesemer @agnivade

@dmitshur dmitshur removed their assignment Apr 17, 2020
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/232868 mentions this issue: [release-branch.go1.14] go/doc: fix detection of whole file examples

gopherbot pushed a commit that referenced this issue May 11, 2020
@flyingmutant @dmitshur
[release-branch.go1.14] go/doc: fix detection of whole file examples
14c92c5 
After CL 211357 (commit 499dc1c),
hasTests and numDecl were not updated properly for function
declarations with parameters, which affected the whole file
example detection logic. This caused examples like

	package foo_test

	func Foo(x int) {
	}

	func Example() {
		fmt.Println("Hello, world!")
		// Output: Hello, world!
	}

to not be detected as whole file ones.

Fixes #38418.
For #38409.

Change-Id: I9ebd47e52d7ee9d91eb6f8e0257511de69b2a402
GitHub-Last-Rev: cc71c31
GitHub-Pull-Request: #37730
Reviewed-on: https://go-review.googlesource.com/c/go/+/222477
Reviewed-by: Agniva De Sarker <agniva.quicksilver@gmail.com>
Reviewed-by: Robert Griesemer <gri@golang.org>
Run-TryBot: Agniva De Sarker <agniva.quicksilver@gmail.com>
TryBot-Result: Gobot Gobot <gobot@golang.org>
(cherry picked from commit c4961dc)
Reviewed-on: https://go-review.googlesource.com/c/go/+/232868
Run-TryBot: Dmitri Shuralyov <dmitshur@golang.org>
Reviewed-by: Gregory Petrosyan <gregory.petrosyan@gmail.com>
@D1CED D1CED mentioned this issue May 11, 2020
Closed
@rhcarvalho rhcarvalho mentioned this issue May 14, 2020
Closed
@gopherbot
Copy link
Contributor

Change https://golang.org/cl/239180 mentions this issue: internal/fetch/internal/doc: fix detection of whole file examples

gopherbot pushed a commit to golang/pkgsite that referenced this issue Jun 22, 2020
@julieqiu
internal/fetch/internal/doc: fix detection of whole file examples
43a5edf 
This CL uses the fix from CL 222477 (golang/go#38409), to fix detection
of whole file examples.

Fixes golang/go#39006
Fixes golang/go#39727

Change-Id: Iaf9240f7637a1723e681cdbb0d06bf36a43d8d2a
Reviewed-on: https://go-review.googlesource.com/c/pkgsite/+/239180
Reviewed-by: Jonathan Amsterdam <jba@google.com>
Reviewed-by: Dmitri Shuralyov <dmitshur@golang.org>
@golang golang locked and limited conversation to collaborators Jun 20, 2021
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Assignees
No one assigned
Labels
FrozenDueToAge NeedsFix The path to resolution is known, but the work has not been done.
Projects
None yet
Milestone
Go1.15
Development

No branches or pull requests
4 participants
@posener @FiloSottile @dmitshur @gopherbot