go/doc: limit factory functions to only ones starting with New

[zigo101]

Please answer these questions before submitting your issue. Thanks!

@rsc suggest to open a new issue, so this one.

What version of Go are you using (go version)?

go version go1.11.1 linux/amd64

Does this issue reproduce with the latest release?

yes

What did you do?

Open https://golang.org/pkg/net/http/, and search the Post and Get functions.

What did you expect to see?

The two functions should be listed at the beginning part, package-level functions zone, of the doc.

What did you see instead?

The two functions are listed under the type Response zone as constructors, which is undesired.
Maybe we should limit constructor functions to the ones start with "New".

[agnivade]

Maybe we should limit constructor functions to the ones start with "New".

Is that what you are proposing ? Then it should be a proposal, rather than a bug.

[zigo101]

It is more a small improvement than a formal proposal.

[agnivade]

Re-titled appropriately.

@griesemer , @rsc

[cznic]

NewFoo is just a convention. I see no reason for it to be enforced by such a widely used tool considering how much existing documentation will become "missing" the constructors in the place where they used to be for many years.

[zigo101]

Yes, NewFoo is ok to be listed in the Foo type zone, but Get and Post shouldn't be listed there.
For many times, I feel some package-level functions are missing for they are moved from the places where they used to be for many years.

[cznic]

That's clear, but you've missed the point of my objection: fixing false positives comes at the cost of new false negatives that exist for a long time, for example here.

Also, wrt #27812 (comment), why shouldn't http.Get be listed as a constructor of *http.Response if that's exactly what the function constructs?

[zigo101]

I don't know, it is my intuition that http.Get is not a constructor of *http.Response.
I think it just happens that http.Get returns a *http.Response.

[dominikh]

What about Create and Generate (concrete examples from code I work with) that very much act as constructors? And a plethora of other examples I could pull out of a hat? You're trying to fix one inconsistency by eliminating a whole class of useful behaviour.

[griesemer]

I think this is overly restrictive. There's plenty of proper factory functions that don't start with New. Personally, I use NewX for functions that create a new X that is a pointer, and sometimes MakeX for a new X that is not a pointer. @dominikh mentioned a few other patterns as well.

The original go/doc heuristic has worked mostly well. The more recent fine-tuning (exclude functions that return more than one type from the list of factory methods) probably overshot a bit into the other direction. We should correct that one, instead. For instance, a final error result should not be considered as an additional type in the decision making. If there's types in a result that are not declared in the current package, we may want to eliminate those functions as well. There's some fine-tuning we can do that should get as 99% there w/o the need to restrict names.

I'm leaning against this proposal.

[zigo101]

how about only view the functions with a Camel-Case style name and the last segment in the Camel-Case name is the same as the base type of a type as the constructors of the type?