net/smtp: document SendMail more

Fixes #9776

Change-Id: I53741fd970244bbfa6874adcb4f1e3d0e7de386b
Reviewed-on: https://go-review.googlesource.com/4162Reviewed-by: Andrew Gerrand <adg@golang.org>

src/net/smtp/example_test.go

@@ -46,14 +46,36 @@ func Example() {
 	}
 }
 
+// variables to make ExamplePlainAuth compile, without adding
+// unnecessary noise there.
+var (
+	from       = "gopher@example.net"
+	msg        = []byte("dummy message")
+	recipients = []string{"foo@example.com"}
+)
+
 func ExamplePlainAuth() {
+	// hostname is used by PlainAuth to validate the TLS certificate.
+	hostname := "mail.example.com"
+	auth := smtp.PlainAuth("", "user@example.com", "password", hostname)
+
+	err := smtp.SendMail(hostname+":25", auth, from, recipients, msg)
+	if err != nil {
+		log.Fatal(err)
+	}
+}
+
+func ExampleSendMail() {
 	// Set up authentication information.
 	auth := smtp.PlainAuth("", "user@example.com", "password", "mail.example.com")
 
 	// Connect to the server, authenticate, set the sender and recipient,
 	// and send the email all in one step.
 	to := []string{"recipient@example.net"}
-	msg := []byte("This is the email body.")
+	msg := []byte("To: recipient@example.net\r\n" +
+		"Subject: discount Gophers!\r\n" +
+		"\r\n" +
+		"This is the email body.\r\n")
 	err := smtp.SendMail("mail.example.com:25", auth, "sender@example.org", to, msg)
 	if err != nil {
 		log.Fatal(err)

src/net/smtp/smtp.go

@@ -264,9 +264,9 @@ func (d *dataCloser) Close() error {
 }
 
 // Data issues a DATA command to the server and returns a writer that
-// can be used to write the data. The caller should close the writer
-// before calling any more methods on c.
-// A call to Data must be preceded by one or more calls to Rcpt.
+// can be used to write the mail headers and body. The caller should
+// close the writer before calling any more methods on c.  A call to
+// Data must be preceded by one or more calls to Rcpt.
 func (c *Client) Data() (io.WriteCloser, error) {
 	_, _, err := c.cmd(354, "DATA")
 	if err != nil {
@@ -281,6 +281,21 @@ var testHookStartTLS func(*tls.Config) // nil, except for tests
 // possible, authenticates with the optional mechanism a if possible,
 // and then sends an email from address from, to addresses to, with
 // message msg.
+//
+// The addresses in the to parameter are the SMTP RCPT addresses.
+//
+// The msg parameter should be an RFC 822-style email with headers
+// first, a blank line, and then the message body. The lines of msg
+// should be CRLF terminated.  The msg headers should usually include
+// fields such as "From", "To", "Subject", and "Cc".  Sending "Bcc"
+// messages is accomplished by including an email address in the to
+// parameter but not including it in the msg headers.
+//
+// The SendMail function and the the net/smtp package are low-level
+// mechanisms and provide no support for DKIM signing, MIME
+// attachments (see the mime/multipart package), or other mail
+// functionality. Higher-level packages exist outside of the standard
+// library.
 func SendMail(addr string, a Auth, from string, to []string, msg []byte) error {
 	c, err := Dial(addr)
 	if err != nil {