Named return parameters are usually used with a naked return statement. Mixing both might lead to confusing behavior, where we'd return a different value than what's held in the return variable. I'm not sure if this is a good change, if it's only meant to improve readability.

I disagree that named parameters are usually used with naked returns. Effective Go describes them as "documentation" and includes an example of exactly this kind of scenario, where multiple returns share a type but the names disambiguate their respective meanings.

The advice I've seen (and given, as a community volunteer) has been roughly, "Named parameters serve as excellent documentation. Naked returns are ok for very short functions and generated code but should be avoided otherwise." Code I've encountered has generally followed the same rule. This is also the advice in the Go team's own style guide, as well as Google's.

I think the next best solution to #30 is adding doc comments to each Gen function describing the meanings of the parameters. That takes many more words and can drift from truth in the event of future API changes. The approach I took also has the advantage that editors will often show return parameter names even in places where they don't show doc comments, like in autocomplete and snippets. In other words, this isn't only about readability but also usability as well.

Another option would be to describe it in the package documentation or readme. Currently, neither mentions the Gen functions at all, since it's a lower level interface. It's also far from where the functions would be used; you'd have to go to pkg.go.dev to check the meanings.

If you'd still prefer a different approach, let me know.

Thanks for all the references, that's convincing!