docs: Add missing docstrings, adjust wording to match standard style

This patch adds a missing docstrings for exported identifiers, and
adjust some of the existing ones to match the standard style.

In some cases, the identifiers were un-exported after noticing they had
no external users.

Besides improving documentation, it also reduces the linter noise
significantly.

internal/smtpsrv/conn.go

@@ -52,7 +52,7 @@ var (
 	disableSPFForTesting = false
 )
 
-// Mode for a socket (listening or connection).
+// SocketMode represents the mode for a socket (listening or connection).
 // We keep them distinct, as policies can differ between them.
 type SocketMode struct {
 	// Is this mode submission?
@@ -81,7 +81,7 @@ var (
 	ModeSubmissionTLS = SocketMode{IsSubmission: true, TLS: true}
 )
 
-// Incoming SMTP connection.
+// Conn represents an incoming SMTP connection.
 type Conn struct {
 	// Main hostname, used for display only.
 	hostname string
@@ -146,10 +146,13 @@ type Conn struct {
 	commandTimeout time.Duration
 }
 
+// Close the connection.
 func (c *Conn) Close() {
 	c.conn.Close()
 }
 
+// Handle implements the main protocol loop (reading commands, sending
+// replies).
 func (c *Conn) Handle() {
 	defer c.Close()
 
@@ -265,6 +268,7 @@ loop:
 	}
 }
 
+// HELO SMTP command handler.
 func (c *Conn) HELO(params string) (code int, msg string) {
 	if len(strings.TrimSpace(params)) == 0 {
 		return 501, "Invisible customers are not welcome!"
@@ -282,6 +286,7 @@ func (c *Conn) HELO(params string) (code int, msg string) {
 	return 250, msg
 }
 
+// EHLO SMTP command handler.
 func (c *Conn) EHLO(params string) (code int, msg string) {
 	if len(strings.TrimSpace(params)) == 0 {
 		return 501, "Invisible customers are not welcome!"
@@ -303,10 +308,12 @@ func (c *Conn) EHLO(params string) (code int, msg string) {
 	return 250, buf.String()
 }
 
+// HELP SMTP command handler.
 func (c *Conn) HELP(params string) (code int, msg string) {
 	return 214, "hoy por ti, mañana por mi"
 }
 
+// RSET SMTP command handler.
 func (c *Conn) RSET(params string) (code int, msg string) {
 	c.resetEnvelope()
 
@@ -319,6 +326,7 @@ func (c *Conn) RSET(params string) (code int, msg string) {
 	return 250, msgs[rand.Int()%len(msgs)]
 }
 
+// VRFY SMTP command handler.
 func (c *Conn) VRFY(params string) (code int, msg string) {
 	// 252 can be used for cases like ours, when we don't really want to
 	// confirm or deny anything.
@@ -326,6 +334,7 @@ func (c *Conn) VRFY(params string) (code int, msg string) {
 	return 252, "You have a strange feeling for a moment, then it passes."
 }
 
+// EXPN SMTP command handler.
 func (c *Conn) EXPN(params string) (code int, msg string) {
 	// 252 can be used for cases like ours, when we don't really want to
 	// confirm or deny anything.
@@ -333,10 +342,12 @@ func (c *Conn) EXPN(params string) (code int, msg string) {
 	return 252, "You feel disoriented for a moment."
 }
 
+// NOOP SMTP command handler.
 func (c *Conn) NOOP(params string) (code int, msg string) {
 	return 250, "You hear a faint typing noise."
 }
 
+// MAIL SMTP command handler.
 func (c *Conn) MAIL(params string) (code int, msg string) {
 	// params should be: "FROM:<name@host>", and possibly followed by
 	// options such as "BODY=8BITMIME" (which we ignore).
@@ -466,6 +477,7 @@ func (c *Conn) secLevelCheck(addr string) bool {
 	return ok
 }
 
+// RCPT SMTP command handler.
 func (c *Conn) RCPT(params string) (code int, msg string) {
 	// params should be: "TO:<name@host>", and possibly followed by options
 	// such as "NOTIFY=SUCCESS,DELAY" (which we ignore).
@@ -531,6 +543,7 @@ func (c *Conn) RCPT(params string) (code int, msg string) {
 	return 250, "You have an eerie feeling..."
 }
 
+// DATA SMTP command handler.
 func (c *Conn) DATA(params string) (code int, msg string) {
 	if c.ehloAddress == "" {
 		return 503, "Invisible customers are not welcome!"
@@ -796,6 +809,7 @@ func boolToStr(b bool) string {
 	return "0"
 }
 
+// STARTTLS SMTP command handler.
 func (c *Conn) STARTTLS(params string) (code int, msg string) {
 	if c.onTLS {
 		return 503, "You are already wearing that!"
@@ -840,6 +854,7 @@ func (c *Conn) STARTTLS(params string) (code int, msg string) {
 	return 0, ""
 }
 
+// AUTH SMTP command handler.
 func (c *Conn) AUTH(params string) (code int, msg string) {
 	if !c.onTLS {
 		return 503, "You feel vulnerable"

internal/smtpsrv/server.go

@@ -28,6 +28,7 @@ var (
 		"how often to reload, ONLY FOR TESTING")
 )
 
+// Server represents an SMTP server instance.
 type Server struct {
 	// Main hostname, used for display only.
 	Hostname string
@@ -70,6 +71,7 @@ type Server struct {
 	PostDataHook string
 }
 
+// NewServer returns a new empty Server.
 func NewServer() *Server {
 	return &Server{
 		addrs:          map[SocketMode][]string{},
@@ -83,6 +85,7 @@ func NewServer() *Server {
 	}
 }
 
+// AddCerts (TLS) to the server.
 func (s *Server) AddCerts(certPath, keyPath string) error {
 	cert, err := tls.LoadX509KeyPair(certPath, keyPath)
 	if err != nil {
@@ -92,36 +95,44 @@ func (s *Server) AddCerts(certPath, keyPath string) error {
 	return nil
 }
 
+// AddAddr adds an address for the server to listen on.
 func (s *Server) AddAddr(a string, m SocketMode) {
 	s.addrs[m] = append(s.addrs[m], a)
 }
 
+// AddListeners adds listeners for the server to listen on.
 func (s *Server) AddListeners(ls []net.Listener, m SocketMode) {
 	s.listeners[m] = append(s.listeners[m], ls...)
 }
 
+// AddDomain adds a local domain to the server.
 func (s *Server) AddDomain(d string) {
 	s.localDomains.Add(d)
 	s.aliasesR.AddDomain(d)
 }
 
+// AddUserDB adds a userdb.DB instance as backend for the domain.
 func (s *Server) AddUserDB(domain string, db *userdb.DB) {
 	s.authr.Register(domain, auth.WrapNoErrorBackend(db))
 }
 
+// AddAliasesFile adds an aliases file for the given domain.
 func (s *Server) AddAliasesFile(domain, f string) error {
 	return s.aliasesR.AddAliasesFile(domain, f)
 }
 
+// SetAuthFallback sets the authentication backend to use as fallback.
 func (s *Server) SetAuthFallback(be auth.Backend) {
 	s.authr.Fallback = be
 }
 
+// SetAliasesConfig sets the aliases configuration options.
 func (s *Server) SetAliasesConfig(suffixSep, dropChars string) {
 	s.aliasesR.SuffixSep = suffixSep
 	s.aliasesR.DropChars = dropChars
 }
 
+// InitDomainInfo initializes the domain info database.
 func (s *Server) InitDomainInfo(dir string) *domaininfo.DB {
 	var err error
 	s.dinfo, err = domaininfo.New(dir)
@@ -137,6 +148,7 @@ func (s *Server) InitDomainInfo(dir string) *domaininfo.DB {
 	return s.dinfo
 }
 
+// InitQueue initializes the queue.
 func (s *Server) InitQueue(path string, localC, remoteC courier.Courier) {
 	q := queue.New(path, s.localDomains, s.aliasesR, localC, remoteC)
 	err := q.Load()
@@ -151,7 +163,7 @@ func (s *Server) InitQueue(path string, localC, remoteC courier.Courier) {
 		})
 }
 
-// PeriodicallyReload some of the server's information, such as aliases and
+// periodicallyReload some of the server's information, such as aliases and
 // the user databases.
 func (s *Server) periodicallyReload() {
 	for range time.Tick(*reloadEvery) {
@@ -167,6 +179,8 @@ func (s *Server) periodicallyReload() {
 	}
 }
 
+// ListenAndServe on the addresses and listeners that were previously added.
+// This function will not return.
 func (s *Server) ListenAndServe() {
 	if len(s.tlsConfig.Certificates) == 0 {
 		// chasquid assumes there's at least one valid certificate (for things