Testable examples must have an `output` comment

[jamietanna]

Your feature request related to a problem? Please describe.

When writing testable examples, the following code is expected:

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

Or a lowercase output:

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

However, when writing the following, without an Output comment:

func ExampleHello() {
    fmt.Println("hello")
}

Then the test compiles correctly, but is not picked up by go test.

We should add a rule which flags when an output comment is missing.

Describe the solution you'd like.

Add a new rule which flags when a testable example - a test that has the test method prefix Example - does not contain a comment with an Output:

Describe alternatives you've considered.

This may not be fit to come into golangci-lint per se, but into one of the other linters.

Additional context.

No response

[maratori]

At first glance it's a good idea.
But if I would like to create an example without output, I can't use //nolint and will have to use exclude-rules in .golangci.yml.
That's because //nolint comment will be added to godoc.

func Example_sameLine() { // nolint:testableexamples
	panic("xxx")
}

// nolint:testableexamples
func Example_previousLine() {
	panic("xxx")
}

[ldez]

@maratori you must write nolint with the directive syntax.

The comment syntax is now deprecated.

From my memories, directives are excluded from the generated godoc.

---

Due to a change of go fmt inside go1.19.
We have to enforce the directive style.

So the option allow-leading-space has been dropped.

The syntax of directives is: [a-zA-Z]+:[a-zA-Z].*.
The spaces around : and after the // must be removed.

// nolint:foo // <-- malformed
//nolint :foo // <-- malformed
//nolint: foo // <-- malformed

//nolint:foo // <-- OK

If you do that your IDE or go fmt will format the directive as a directive and it will not add extra space.

Related to:
#3002
#1658 (comment)

[maratori]

@ldez you are right. Directives are excluded form godoc.
The only exception if it's placed on the same line.

//nolint:testableexamples
func Example_previousLine() {
	panic("xxx")
}

func Example_sameLine() { //nolint:testableexamples
	panic("xxx")
}

Ok, then I'll create a linter.

[ldez]

closed by #3170