go/doc,x/pkgsite: rethink order for factory functions #39813
For my package: https://godoc.org/github.com/rocketlaunchr/dataframe-go/forecast
I have a function:
Unfortunately my function is categorized under
I assume this issue would also be present in
The text was updated successfully, but these errors were encountered:
Thanks for reporting. This behavior is a part of the
This is working as intended given the current implementation, see the relevant code in
Note that this is a heuristic, so it is expected it may not produce absolutely ideal results in all cases. The heuristic was chosen with a goal of working as well as possible as often as possible. Based on your description, it sounds this is a case where it's not optimal.
We could consider changing the heuristic to require associated type of factory functions to be the first result type, rather than the first visible result type. In order to gain confidence that it would be a net positive to make such a change, we could test it out on a large corpus of Go packages and evaluate whether it results in more changes that are more helpful than unhelpful.
The factory-function heuristics work great the vast majority of the time. It may be surprising initially, but once you understand the organization it's very valuable. Perhaps we need to work on the "surprising" aspect, but breaking them out from under their respective types is a grass-is-greener proposition, since we trade one use case for another and it's not clear it's an improvement.
I understand the sentiment, but I believe this has a couple of harmful effects:
My suggestion is, if your package has constructor methods that you expect to require regular usage, and you want to spotlight them, put some examples in the Overview section at the top. In #28006 you mention net/http but I have never wondered how to use that package because the first thing you see in the docs are examples of
This sounds like a change that could handle @pjebs specific issue without negative impacts.
I've only just worked out why I keep failing to find things in the navigation on pkg.go.dev, and it's this problem. I'd been assuming the navigation is broken and using Ctrl-F.
I would like to request that at least one of the navigation sections be useful for finding any function in the package, regardless of what type(s) it returns.
This could be done by making Functions list all functions, or by arranging the index in alphabetical order by name. Both were things I expected to be the case already.
In my case, I was looking up
From my understanding, the following suggestion would help, no?