go/doc,x/pkgsite: rethink order for factory functions

[pjebs]

For my package: https://godoc.org/github.com/rocketlaunchr/dataframe-go/forecast

I have a function:
func Forecast(ctx context.Context, sdf interface{}, r *dataframe.Range, alg ForecastingAlgorithm, cfg interface{}, n uint, evalFunc EvaluationFunc) (interface{}, []Confidence, float64, error) which returns an interface{} as the first return value.

Unfortunately my function is categorized under type Confidence when it should not be.

I assume this issue would also be present in pkg.go.dev, but my package has been banned from there (despite the person in charge saying it will be allowed many many months ago), so I can't check if this issue persists.

[cagedmantis]

/cc @dmitshur

[dmitshur]

Thanks for reporting. This behavior is a part of the go/doc package, so it affects all places that use it for displaying Go documentation.

The Forecast function is being considered as a "factory function" for the type Confidence because it returns a slice of that type, and all other return value types are predeclared type.

This is working as intended given the current implementation, see the relevant code in go/doc here.

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.

/cc @griesemer @julieqiu

[zigo101]

This is a design issue which breaks user expectations and has been reported for several times: #28006 and #38666

Personally, I would like to list such functions both in the function list and the method list of a type. (BTW, I have implemented this in an experimental project.)

[julieqiu]

Let's close this in favor of using #39813 as the tracking issue for considering changes to the "factory function" behavior.

[julieqiu]

(Meant to close #40927.)