x/pkgsite: reflect.Kind-type constants do not appear in Constants section of reflect docs

[themowski]

(Note -- the more I think about this, the more I think that it might actually be an issue with the source code for the reflect package not being correctly commented, so the doc parser is failing. However, I noticed the issue on the website, so I figured I'd log it as a site issue.)

What is the URL of the page with the issue?

https://pkg.go.dev/reflect#pkg-index

What is your user agent?

Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:78.0) Gecko/20100101 Firefox/78.0

What did you do?

I was looking at the encoding/json/decode.go source code here: https://cs.opensource.google/go/go/+/refs/tags/go1.17.1:src/encoding/json/decode.go;l=164;drc=refs%2Ftags%2Fgo1.17.1

I noticed that reflect.Ptr is struck out, which I assume means deprecated.

This seemed weird to me, because it's in the standard library, calling another standard library package. I clicked on the reflect.Ptr link, which took me here: https://cs.opensource.google/go/go/+/refs/tags/go1.17.1:src/reflect/type.go;drc=refs%2Ftags%2Fgo1.17.1;l=274

This was unhelpful to me, so I went to pkg.go.dev to try to find what reflect.Ptr is, and why it might be crossed out. I could not find it listed in the index for the reflect package, and the "Constants" section of the documentation was empty.

I used my browser's Find functionality to look for it, and it turned out that it, along with a huge list of reflect.Kind constants, was buried in the documentation for the reflect.Kind type.

What did you expect to see?

Since reflect.Ptr is a constant, I would have expected to see it in the "Constants" section.

By way of example, the os.Stdin constant appears in the "Constants" section of that page:

https://pkg.go.dev/os@go1.17.1#pkg-constants

What did you see instead?

• The reflect.Kind constants were listed with the documentation for reflect.Kind. This really does not help someone who is trying to understand what those types are -- if I had known that reflect.Ptr was a reflect.Kind, then I probably would not have had to look it up, because that's exactly the question I was trying to answer.
• It was confusing to me that reflect.Ptr did not show up in either the "Constants" section or the "Index" section.
• Having to use my browser's Find functionality was inconvenient.

Postmortem / bonus weirdness

I later discovered that reflect.Ptr is deprecated in favor of reflect.Pointer on the master branch as of right now, so that explains why reflect.Ptr would be crossed out... except that I was specifically looking at the 1.17.1 code, NOT the master code. This seems to suggest that there's also an issue with the code introspection functionality available in the code browser -- the deprecation information and link to the definition of reflect.Ptr were targeting master, but I was looking at 1.17.1. In the screenshot below, you can see that reflect.Ptr is actually deprecated, and does exist on line 274 (like in the previous screenshot) -- but on the master branch, not for Go 1.17.1.

https://cs.opensource.google/go/go/+/master:src/reflect/type.go;l=274?q=Kind&ss=go%2Fgo

[jba]

I think this is a consequence of the way the go/doc package works: it groups constants with their type if the type is defined in the package, and other constants in the "Constants" section (which explains os.Stdin). I don't think there's anything pkgsite can do to "fix" that, if indeed it should be fixed.

On the bright side, pkgsite's new symbol search feature finds it: https://beta.pkg.go.dev/search?q=%23Ptr+reflect.

[themowski]

Thanks for looking into this! I still find the behavior to be pretty inaccessible, especially putting myself in the shoes of a newcomer, but I agree that it's out of your scope if all you're doing is parsing output of another tool.