doc: go:noinline directives in godoc

[randall77]

In the docs for runtime.Callers https://golang.org/pkg/runtime/#Callers , the text ends with go:noinline. We probably shouldn't include that part (or any go: directive) in the godoc.

This occurs in some internal packages as well, like runtime/internal/atomic.

[agnivade]

I think this should be handled in go/doc.Func itself. When doc.New is called, Func.Doc should not contain go: directives.

@griesemer

[bcmills]

My impression from previous discussions (such as #32816 (comment)) is that //go: directives are intended to be placed before the affected declaration, separated from the doc comment by a blank line. Does that work for //go:noinline directives?

[bcmills]

That does, at least, suggest that we should have a vet or lint warning for misplaced //go: directives. (CC @ianthehat @dominikh)

[ianlancetaylor]

I don't think we should have godoc remove these comments, as that would be confusing when the function's doc is in fact intended to include such a comment. Similarly, I don't think a go vet warning would be appropriate, although a golint one would be fine.

Let's just fix the cases as @bcmills suggests, which is how it is supposed to be used anyhow.

[toothrot]

Adding NeedsFix, as positioning the //go: directives resolves the issue, and it seems straightforward.

runtime.KeepAlive is a good example:

go/src/runtime/mfinal.go

Lines 424 to 427 in 115e4c9

	// Mark KeepAlive as noinline so that it is easily detectable as an intrinsic.
	//go:noinline
	// KeepAlive marks its argument as currently reachable.

runtime.KeepAlive docs: https://godoc.org/runtime#KeepAlive

[gopherbot]

Change https://golang.org/cl/195818 mentions this issue: runtime: remove unneeded noinline directives

[randall77]

Closing. runtime.Callers has been fixed, and it sounds like we should just move the comments instead of fixing godoc.