stylecheck: flag doc references to nonexisting objects

[dominikh]

golang/go#51082 proposes to add new markup for Go documentation. Part of that is explicit syntax for linking to identifiers. We could flag references that do not resolve.

Suggested by @seankhliao

[thepudds]

Part of that is explicit syntax for linking to identifiers. We could flag references that do not resolve.

Hi @dominikh, if this was implemented, presumably it would be reasonable to also flag if a URL link in the comment does not have a corresponding link URL definition at the bottom? (In other words, no Go identifier or symbol involved, just a URL).

// For an introduction to this package, see the article
// “[JSON & Go].”
//
// [JSON and Go]: https://golang.org/doc/articles/json_and_go.html

(And maybe that is intended to be covered already -- I am just trying to be explicit).

[dominikh]

@thepudds Can we differentiate unresolved references from text which just wants to be enclosed in brackets and doesn't denote a link? Linking to identifiers has a number of restrictions to avoid false positives on godoc's end which would also aid us. For URLs, no such restrictions exist.

[thepudds]

Hi @dominikh, that’s a fair question. (And I see that you are of course right that the proposal only has the additional false positive safeguards for linking to identifiers).

Perhaps a more robust check might be to flag if a properly formatted and positioned link URL definition does not have a corresponding URL link in the comment.

The proposal already reformats those into a different group separated by a blank line, but that only helps if you have at least two total.

At least for me, flagging an accidentally out of sync link definition (due to a typo, a subsequent inconsistent edit, bad copy/paste, …) seems useful, so maybe one additional way to cut down on noise might be to only report if there is at least one piece of text in the comment enclosed in brackets that is not covered by some link definition at the bottom. Alternatively, it could just flag any unused link definition.

[dominikh]

I'll definitely explore these things when I write the check. Thanks for making me aware that URLs are also worth checking.