mirror of
https://github.com/wneessen/go-mail.git
synced 2024-11-08 23:12:54 +01:00
Refine function comments to include return type details
This is a sync with the net/smtp upstream as committed here: 1d45a7ef56 (diff-4f6f6bdb9891d4dd271f9f31430420a2e44018fe4ee539576faf458bebb3cee4)
.
This commit is contained in:
parent
01e5deb357
commit
5dbb1e6dde
6 changed files with 16 additions and 11 deletions
|
@ -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.
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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:
|
||||
|
|
|
@ -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.
|
||||
|
|
|
@ -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}
|
||||
}
|
||||
|
|
14
smtp/smtp.go
14
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 Data call or another Rcpt call.
|
||||
// A call to Rcpt must be preceded by a call to [Client.Mail] and may be followed by
|
||||
// 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 {
|
||||
|
|
Loading…
Reference in a new issue