Basic docs for most classes

4 files changed, 23 insertions, 0 deletions

diff --git a/app/models/action_mailbox/inbound_email/incineratable.rb b/app/models/action_mailbox/inbound_email/incineratable.rb
index 198846422c..a049b88b69 100644
--- a/app/models/action_mailbox/inbound_email/incineratable.rb
+++ b/app/models/action_mailbox/inbound_email/incineratable.rb
@@ -1,3 +1,6 @@
+# Ensure that the `InboundEmail` is automatically scheduled for later incineration if the status has been
+# changed to `processed`. The later incineration will be invoked at the time specified by the 
+# `ActionMailbox.incinerate_after` time using the `IncinerationJob`.
 module ActionMailbox::InboundEmail::Incineratable
   extend ActiveSupport::Concern
 
diff --git a/app/models/action_mailbox/inbound_email/incineratable/incineration.rb b/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
index 801cc0c8b9..50861bc64b 100644
--- a/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
+++ b/app/models/action_mailbox/inbound_email/incineratable/incineration.rb
@@ -1,3 +1,7 @@
+# Command class for carrying out the actual incineration of the `InboundMail` that's been scheduled 
+# for removal. Before the incineration – which really is just a call to `#destroy!` – is run, we verify
+# that it's both eligible (by virtue of having already been processed) and time to do so (that is, 
+# the `InboundEmail` was processed after the `incinerate_after` time).
 class ActionMailbox::InboundEmail::Incineratable::Incineration
   def initialize(inbound_email)
     @inbound_email = inbound_email
diff --git a/app/models/action_mailbox/inbound_email/message_id.rb b/app/models/action_mailbox/inbound_email/message_id.rb
index 70d39d1e33..dc17e48e74 100644
--- a/app/models/action_mailbox/inbound_email/message_id.rb
+++ b/app/models/action_mailbox/inbound_email/message_id.rb
@@ -1,3 +1,9 @@
+# The `Message-ID` as specified by rfc822 is supposed to be a unique identifier for that individual email. 
+# That makes it an ideal tracking token for debugging and forensics, just like `X-Request-Id` does for 
+# web request.
+#
+# If an inbound email does not, against the rfc822 mandate, specify a Message-ID, one will be generated
+# using the approach from `Mail::MessageIdField`.
 module ActionMailbox::InboundEmail::MessageId
   extend ActiveSupport::Concern
 
@@ -6,6 +12,9 @@ module ActionMailbox::InboundEmail::MessageId
   end
 
   module ClassMethods
+    # Create a new `InboundEmail` from the raw `source` of the email, which be uploaded as a Active Storage
+    # attachment called `raw_email`. Before the upload, extract the Message-ID from the `source` and set
+    # it as an attribute on the new `InboundEmail`.
     def create_and_extract_message_id!(source, **options)
       create! message_id: extract_message_id(source), **options do |inbound_email|
         inbound_email.raw_email.attach io: StringIO.new(source), filename: "message.eml", content_type: "message/rfc822"
diff --git a/app/models/action_mailbox/inbound_email/routable.rb b/app/models/action_mailbox/inbound_email/routable.rb
index 8f5b0ddd39..f042fa4f57 100644
--- a/app/models/action_mailbox/inbound_email/routable.rb
+++ b/app/models/action_mailbox/inbound_email/routable.rb
@@ -1,3 +1,8 @@
+# A newly received `InboundEmail` will not be routed synchronously as part of ingress controller's receival.
+# Instead, the routing will be done asynchronously, using a `RoutingJob`, to ensure maximum parallel capacity.
+#
+# By default, all newly created `InboundEmail` records that have the status of `pending`, which is the default,
+# will be scheduled for automatic, deferred routing.
 module ActionMailbox::InboundEmail::Routable
   extend ActiveSupport::Concern
 
@@ -5,10 +10,12 @@ module ActionMailbox::InboundEmail::Routable
     after_create_commit :route_later, if: :pending?
   end
 
+  # Enqueue a `RoutingJob` for this `InboundEmail`.
   def route_later
     ActionMailbox::RoutingJob.perform_later self
   end
 
+  # Route this `InboundEmail` using the routing rules declared on the `ApplicationMailbox`.
   def route
     ApplicationMailbox.route self
   end