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.