go/importer: documentation of lookup parameter of ForCompiler can be clarified

[adonovan]

This CL https://go.dev/cl/184079 added Deprecated to ForCompiler, but Russ and I think this was a mistake: it seems to apply only to the behavior of allowing lookup to be nil. https://go.dev/cl/773040 needs this issue in order to remedy the mistake, since it changes api/next, which means it also needs proposal review committee approval. Sigh.

@griesemer @rsc

[gopherbot]

Change https://go.dev/cl/773040 mentions this issue: go/importer: un-deprecate importer.ForCompiler

[gabyhelp]

Related Issues

• x/tools/go/packages: undeprecate Load* mode flags (or fix Need* flags) #70470 (closed)

_{(Emoji vote if this was helpful or unhelpful; more detailed feedback welcome in this discussion.)}

[dmitshur]

@prattmic pointed out a deviation in deprecation comment detection between cmd/api check and pkgsite. As is, api check considers the go/importer.ForCompiler function as deprecated, but pkgsite does not:

It seems pkgsite's behavior is correct, and api check has a false positive. Both at https://go.dev/wiki/Deprecated and https://go.dev/ref/mod#go-mod-file-module-deprecation it is made pretty clear that a "Deprecated:" prefix must be at the start of a paragraph; it cannot be in the middle of a paragraph:

To signal that an identifier should not be used, add a paragraph to its doc comment that begins with Deprecated: followed by some information about the deprecation, and a recommendation on what to use instead, if applicable. The paragraph does not have to be the last paragraph in the doc comment.

A module can be marked as deprecated in a block of comments containing the string Deprecated: (case-sensitive) at the beginning of a paragraph.

(Emphasis mine.)

The ForCompiler documentation has 3 paragraphs, and none of them begin with "Deprecated:". https://go.dev/cl/773040 rephrases documentation to be more clear and should be applied regardless, but there's another separate issue to fix api check's deprecation comment detection logic to match the specification. (Filed #79145 for it.)

[gopherbot]

Change https://go.dev/cl/774881 mentions this issue: cmd/api: fix false positive in isDeprecated