x/tools/go/analysis/passes/tests: should it re-use go/doc's example classification logic, or continue to implement its own?

[dmitshur]

A part of the functionality in the function checkExample parses the name of the example and reports if it refers to an unknown identifier, field, or method.

Before #23864 was resolved, there was no choice but for tests to implement this logic itself. Now that #23864 is resolved, it may be possible for tests to reuse some of the logic from go/doc in Go 1.14 and newer.

This issue is to investigate and answer the question of: should it? Would it be better to reuse that logic, or is it better to continue to implement the example naming classification a second time for the needs of tests?

Note that the text of diagnostics that the tests pass emits should not be made worse if this implementation change were to happen.

/cc @jayconrod @matloob @bcmills

[matloob]

This change might be cumbersome because we'd still have to match up the examples returned from go/doc.Examples with the one that's being checked in checkExample, and some of the logic in checkExample will need to stay (checking arguments, return types) because go/doc.Examples throws the function signature.

[jayconrod]

I don't know much about the tests pass, but doesn't it need to identify functions that are intended by the user to be examples but aren't returned by go/doc.Examples? If that's the case, then it has to have its own implementation.

[dmitshur]

It sounds like there isn't a way to use the new example classification functionality in go/doc in a beneficial way for the needs of tests. I'll close this for now, but if we later find some opportunity to benefit from go/doc after all, we can reopen this.