From 73375abec3ce05ea9a1d836ba210d0bb696d915f Mon Sep 17 00:00:00 2001
From: Nathan Fisher <jeang3nie@hitchhiker-linux.org>
Date: Wed, 24 May 2023 13:22:47 -0400
Subject: [PATCH] Add doc comments for all status subcodes

---
 src/status/error.rs |  1 +
 src/status/mod.rs   | 21 +++++++++++++++++++--
 2 files changed, 20 insertions(+), 2 deletions(-)

diff --git a/src/status/error.rs b/src/status/error.rs
index e64f26d..0ba7b82 100644
--- a/src/status/error.rs
+++ b/src/status/error.rs
@@ -1,6 +1,7 @@
 use std::fmt;
 
 #[derive(Debug, Clone, PartialEq)]
+/// The receiving server sent an unrecognized or invalid status code
 pub struct Error;
 
 impl fmt::Display for Error {
diff --git a/src/status/mod.rs b/src/status/mod.rs
index ee24b2b..4508ea9 100644
--- a/src/status/mod.rs
+++ b/src/status/mod.rs
@@ -117,13 +117,20 @@ impl TryFrom<u8> for TemporaryFailure {
 }
 
 #[derive(Debug, Clone, PartialEq)]
-/// Status codes representing that a permanent failure has occurred and the sending server should
-/// not resend the message.
+/// Status codes representing that a permanent failure has occurred and the sending
+/// server should not resend the message.
 pub enum PermanentFailure {
+    /// Something is wrong with the mailserver, and you should not try to resend
+    /// your message.
     PermanentError = 0,
+    /// The mailbox you are trying to send to doesn't exist, and the mailserver
+    /// won't accept your message.
     MailboxNonexistent = 1,
+    /// The mailbox you are trying to send to existed once, but doesn't anymore.
     MailboxGone = 2,
+    /// This mailserver doesn't serve mail for the hostname you provided.
     DomainNotServiced = 3,
+    /// Your request is malformed, and won't be accepted by the mailserver.
     BadRequest = 9,
     Other,
 }
@@ -147,10 +154,20 @@ impl TryFrom<u8> for PermanentFailure {
 #[derive(Debug, Clone, PartialEq)]
 /// Status codes representing an authentication failure
 pub enum AuthenticationFailure {
+    /// This mailserver doesn't accept anonymous mail, and you need to repeat your
+    /// request with a certificate.
     CertificateRequired = 0,
+    /// Your certificate was validated, but you are not allowed to send mail to
+    /// that mailbox.
     UnauthorizedSender = 1,
+    /// Your certificate might be legitimate, but it has a problem - it is expired,
+    /// or it doesn't point to a valid Misfin identity, etc.
     CertificateInvalid = 2,
+    /// Your certificate matches an identity that the mailserver recognizes, but
+    /// the fingerprint has changed, so it is rejecting your message.
     IdentityMismatch = 3,
+    /// The mailserver needs you to complete a task to confirm that you are a
+    /// legitimate sender. (This is reserved for a Hashcash style anti-spam measure).
     ProofRequired = 4,
     Other,
 }