Change https://go.dev/cl/415554 mentions this issue: go/doc/comment: support doc links to builtins

Personally I don't like something like [builtin.len]. That's not what it looks like in the code. It seems confusing. Maybe we can do something about the builtin identifiers but this approach doesn't seem right to me.

/builtin#len or builtin len is how it's routed in documentation so it makes sense to me to continue those patterns. If you had asked me to try to link to the docs for len in the new system without looking up how it's done [builtin.len] would be my first try, but I've spent a lot more time in the guts of the documentation system than your average Go programmer.

Personally I don't like something like [builtin.len]. That's not what it looks like in the code. It seems confusing. Maybe we can do something about the builtin identifiers but this approach doesn't seem right to me.

Think you are correct. It makes sense for the documentation author, but not for the documentation reader, who might try literally typing "builtin.len".

I don't necessarily want to suggest linking a plain [len] to the builtin docs, because it looks too much like a normal named link.

Maybe [builtin.Len] can get its name/text rewritten to "Len" in the output. Is that too suprising for something that might not be used that often?

If we do this, the next thing that will happen is that people insist every mention of [int] or [bool] or [len] be linked in doc comments. I think we can assume that people reading doc comments know about the Go language itself, including the builtins.

This proposal has been added to the active column of the proposals project
and will now be reviewed at the weekly proposal review meetings.
— rsc for the proposal review group

It might be helpful if I narrow this down to my specific use-case, which was top-level package documentation mentioning comparable, which people might not be familiar with yet. On reflection, I think this will only temporarily be something anyone feels like doc linking, and it is probably the wrong thing to do even then.

I agree with rsc that we can expect Go programmers to be familiar with the builtins. Where they aren't yet (which is fine!), its not the job of every single Go package to explain them.

I would still argue in general: If someone is writing educational code or tutorials for new Go programmers, I think they could very reasonably want to doclink a builtin. However, that is not my use-case so I can't argue this with any confidence.

Therefore I withdraw/retract this proposal

This proposal has been declined as retracted.
— rsc for the proposal review group