Refine function comments to include return type details

This is a sync with the net/smtp upstream as committed here: 1d45a7ef56 (diff-4f6f6bdb9891d4dd271f9f31430420a2e44018fe4ee539576faf458bebb3cee4).

smtp/auth_cram_md5.go

@@ -27,7 +27,7 @@ type cramMD5Auth struct {
 	username, secret string
 }
 
-// CRAMMD5Auth returns an Auth that implements the CRAM-MD5 authentication
+// CRAMMD5Auth returns an [Auth] that implements the CRAM-MD5 authentication
 // mechanism as defined in RFC 2195.
 // The returned Auth uses the given username and secret to authenticate
 // to the server using the challenge-response mechanism.

smtp/auth_cram_md5_118.go

@@ -27,7 +27,7 @@ type cramMD5Auth struct {
 	username, secret string
 }
 
-// CRAMMD5Auth returns an Auth that implements the CRAM-MD5 authentication
+// CRAMMD5Auth returns an [Auth] that implements the CRAM-MD5 authentication
 // mechanism as defined in RFC 2195.
 // The returned Auth uses the given username and secret to authenticate
 // to the server using the challenge-response mechanism.

smtp/auth_login.go

@@ -43,7 +43,7 @@ const (
 	LoginXDraftPasswordChallenge = "Password\x00"
 )
 
-// LoginAuth returns an Auth that implements the LOGIN authentication
+// LoginAuth returns an [Auth] that implements the LOGIN authentication
 // mechanism as it is used by MS Outlook. The Auth works similar to PLAIN
 // but instead of sending all in one response, the login is handled within
 // 3 steps:

smtp/auth_plain.go

@@ -23,7 +23,7 @@ type plainAuth struct {
 	host                         string
 }
 
-// PlainAuth returns an Auth that implements the PLAIN authentication
+// PlainAuth returns an [Auth] that implements the PLAIN authentication
 // mechanism as defined in RFC 4616. The returned Auth uses the given
 // username and password to authenticate to host and act as identity.
 // Usually identity should be the empty string, to act as username.

smtp/auth_xoauth2.go

@@ -8,6 +8,11 @@ type xoauth2Auth struct {
 	username, token string
 }
 
+// XOAuth2Auth returns an [Auth] that implements the XOAuth2 authentication
+// mechanism as defined in the following specs:
+//
+// https://developers.google.com/gmail/imap/xoauth2-protocol
+// https://learn.microsoft.com/en-us/exchange/client-developer/legacy-protocols/how-to-authenticate-an-imap-pop-smtp-application-by-using-oauth
 func XOAuth2Auth(username, token string) Auth {
 	return &xoauth2Auth{username, token}
 }

smtp/smtp.go

@@ -60,7 +60,7 @@ type Client struct {
 	dsnrntype string // dsnrntype defines the recipient notify option in case DSN is enabled
 }
 
-// Dial returns a new Client connected to an SMTP server at addr.
+// Dial returns a new [Client] connected to an SMTP server at addr.
 // The addr must include a port, as in "mail.example.com:smtp".
 func Dial(addr string) (*Client, error) {
 	conn, err := net.Dial("tcp", addr)
@@ -71,7 +71,7 @@ func Dial(addr string) (*Client, error) {
 	return NewClient(conn, host)
 }
 
-// NewClient returns a new Client using an existing connection and host as a
+// NewClient returns a new [Client] using an existing connection and host as a
 // server name to be used when authenticating.
 func NewClient(conn net.Conn, host string) (*Client, error) {
 	text := textproto.NewConn(conn)
@@ -164,7 +164,7 @@ func (c *Client) StartTLS(config *tls.Config) error {
 }
 
 // TLSConnectionState returns the client's TLS connection state.
-// The return values are their zero values if StartTLS did
+// The return values are their zero values if [Client.StartTLS] did
 // not succeed.
 func (c *Client) TLSConnectionState() (state tls.ConnectionState, ok bool) {
 	tc, ok := c.conn.(*tls.Conn)
@@ -247,7 +247,7 @@ func (c *Client) Auth(a Auth) error {
 // If the server supports the 8BITMIME extension, Mail adds the BODY=8BITMIME
 // parameter. If the server supports the SMTPUTF8 extension, Mail adds the
 // SMTPUTF8 parameter.
-// This initiates a mail transaction and is followed by one or more Rcpt calls.
+// This initiates a mail transaction and is followed by one or more [Client.Rcpt] calls.
 func (c *Client) Mail(from string) error {
 	if err := validateLine(from); err != nil {
 		return err
@@ -273,8 +273,8 @@ func (c *Client) Mail(from string) error {
 }
 
 // Rcpt issues a RCPT command to the server using the provided email address.
-// A call to Rcpt must be preceded by a call to Mail and may be followed by
+// A call to Rcpt must be preceded by a call to [Client.Mail] and may be followed by
-// a Data call or another Rcpt call.
+// a [Client.Data] call or another Rcpt call.
 func (c *Client) Rcpt(to string) error {
 	if err := validateLine(to); err != nil {
 		return err
@@ -302,7 +302,7 @@ func (d *dataCloser) Close() error {
 // Data issues a DATA command to the server and returns a writer that
 // 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.
+// Data must be preceded by one or more calls to [Client.Rcpt].
 func (c *Client) Data() (io.WriteCloser, error) {
 	_, _, err := c.cmd(354, "DATA")
 	if err != nil {