x/pkgsite, x/website, x/tools/godoc: factory functions are displayed in a way that can cause confusion #40223
What did you do?
My golang program needs to find out if a path refers to an existing directory. I need to find out how to do that. Here's what I did:
type FileInfo func Lstat(name string) (FileInfo, error) func Stat(name string) (FileInfo, error)
What did you expect to see?
I expected to see
Constants Variables func Chdir(dir string) error func Chmod(name string, mode FileMode) error ... func Setenv(key, value string) error func Stat(name string) (FileInfo, error) // <--- here func Symlink(oldname, newname string) error ... type File ... type FileInfo ... type FileMode ...
What did you see instead?
Constants Variables func Chdir(dir string) error func Chmod(name string, mode FileMode) error ... func UserConfigDir() (string, error) func UserHomeDir() (string, error) type File ... type FileInfo func Lstat(name string) (FileInfo, error) func Stat(name string) (FileInfo, error) // <--- here type FileMode ...
The text was updated successfully, but these errors were encountered:
There are many ways to save readers from confusing factory functions with struct receiver funcs. Here are three I thought of:
Will you please reconsider fixing this issue?
EDIT: s/generator func/factory func/g
@seankhliao I see that you downvoted my issue report. I think this means that you know something that I don't. Would you please explain it?
My intention was to suggest we use #39813 for tracking improvements to the heuristic of when to consider a function as a "factory function". However, this issue seems slightly different, as it's about the way factory functions are displayed. Reopening so we can consider this further.
@mleonhard I'm sorry that you had some confusion on this.
Generally speaking, it's easy to recognize constructors because they have no receiver. Take for example the Cuelang Godoc, in particular the
That said, I could see introducing a very small change to call a little more attention to these methods. Perhaps if the circle next to them was filled rather than hollow? I think that would make it easier to spot whilst scanning the overall package, without negatively affecting what seems to be a long-lasting and battle-tested structure.
(...Hm, I realize now that golang.org/pkg is actually a little different from godoc.org, for example missing the bullet, but it could be added.)