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

[dmitshur]

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

[posener]

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

[FiloSottile]

@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]

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]

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

/cc @griesemer @agnivade

[gopherbot]

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

[gopherbot]

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