proposal: x/tools/go/analysis/analysisutil: publish ExtractDoc

[hyangah]

ExtractDoc is a convention originally developed to fix a go documentation issue and adopted in all analyzers in x/tools/go/analysis/passes. This allows analyzers to provide consistent documentation in pkg.go.dev, go doc, and *checkers.

I think this is a useful convention that can be adopted by any x/tools/go/analysis analyzers, and propose to move it to public so other analyzer authors can adopt and use this convention.

golang.org/x/tools/go/analysis/analysisutil is an option.

cc @adonovan

[cherrymui]

I think new public API on x/tools still needs a proposal. So maybe you want to file a proposal. Thanks.

cc @timothy-king @matloob @zpavlinovic

[adonovan]

We propose to create a new package, analysisutil, that initially holds the existing internal ExtractDoc and MustExtractDoc functions. Other functions may follow in due course.

So maybe you want to file a proposal. Thanks.

Yep. Fixed that for you, Hana. ;-)

[adonovan]

Perhaps this function belongs in go/analysis itself, alongside the Analyzer interface. We're careful about adding to that package to avoid unnecessary dependencies, but in this case it doesn't add any.

(The widely used analysisutil.Format and Imports helpers also don't add dependencies, and I think they too should be published, but perhaps a separate analysisutil package still makes sense for these sorts of things which are useful only to programs on one side the driver/checker interface.)