net/smtp: Address schemes

[gopherbot]

by Ephrones:

Dial() wants as addr a scheme as defined in http://golang.org/pkg/net/#Dial.

SendMail() calls Dial() internally, but without looking at its source one can only guess
from the docstring what scheme it needs as addr.

It gets fun when you create a PlainAuth(), which wants a host (that is basically addr
but without the colon separated port). I thought: “Ah, already got that!” and put in
my addr from before. Now you get a rather meaningless “wrong host name” error.
As it turns out this one is thrown in net/smtp/auth.go because host doesn’t like the
port.

imho Dial() should have host and port as separate arguments, but I see that the API
can’t be changed now.

So I suggest the following:
1. Clarify the docstrings (reference to Dial() in net in all Dial() docstrings and in
SendMail)
2. Improve “wrong host name” to Sprintf("wrong host name (%s)", hostname)

Pull request coming, will reference this issue.

[gopherbot]

Comment 1:

CL https://golang.org/cl/179050043 mentions this issue.

[minux]

Comment 2:

i think it's obvious what Dial takes, we
shouldn't need to specify that every Dial
function/method uses the convention of
net.Dail.
the 2nd point about error message seems
plausible though.
we're in 1.4 release freeze, please ping
after 1.4 is out. Thanks.

[gopherbot]

Comment 3 by Ephrones:

> i think it's obvious what Dial takes
Well, it took me about half an hour to find that out. Sharing the same name doesn’t
intrinsically mean they take the same arguments. Plus, how should I know I need to look
at net.Dial when all I wanted to do was use smtp.Dial to send a mail?
Btw, some Dial-methods already reference to net.Dial
I think it’s only sensible to add that information because it’s not obvious what
addr wants/accepts (e.g. named ports possible).
> we're in 1.4 release freeze
Will 1.5 use Github? It was quite interesting getting this to work.

[rsc]

Maybe the docs could be made clearer.