Add documentation on poll messages and an outline of Code structure

-------------
Created by MOE: https://github.com/google/moe
MOE_MIGRATED_REVID=133713736

java/google/registry/flows/poll/PollAckFlow.java

@@ -35,12 +35,18 @@ import google.registry.flows.TransactionalFlow;
 import google.registry.model.eppoutput.EppOutput;
 import google.registry.model.poll.MessageQueueInfo;
 import google.registry.model.poll.PollMessage;
+import google.registry.model.poll.PollMessageExternalKeyConverter;
 import google.registry.model.poll.PollMessageExternalKeyConverter.PollMessageExternalKeyParseException;
 import javax.inject.Inject;
 import org.joda.time.DateTime;
 
 /**
- * An EPP flow for acknowledging poll messages.
+ * An EPP flow for acknowledging {@link PollMessage}s.
+ *
+ * <p>Registrars refer to poll messages using an externally visible id generated by
+ * {@link PollMessageExternalKeyConverter}. One-time poll messages are deleted from Datastore once
+ * they are ACKed, whereas autorenew poll messages are simply marked as read, and won't be delivered
+ * again until the next year of their recurrence.
  *
  * @error {@link PollAckFlow.InvalidMessageIdException}
  * @error {@link PollAckFlow.MessageDoesNotExistException}

java/google/registry/flows/poll/PollRequestFlow.java

@@ -28,10 +28,17 @@ import google.registry.flows.LoggedInFlow;
 import google.registry.model.eppoutput.EppOutput;
 import google.registry.model.poll.MessageQueueInfo;
 import google.registry.model.poll.PollMessage;
+import google.registry.model.poll.PollMessageExternalKeyConverter;
 import javax.inject.Inject;
 
 /**
- * An EPP flow for requesting poll messages.
+ * An EPP flow for requesting {@link PollMessage}s.
+ *
+ * <p>This flow uses an eventually consistent Datastore query to return the oldest poll message for
+ * the registrar, as well as the total number of pending messages. Note that poll messages whose
+ * event time is in the future (i.e. they are speculative and could still be changed or rescinded)
+ * are ignored. The externally visible id for the poll message that the registrar sees is generated
+ * by {@link PollMessageExternalKeyConverter}.
  *
  * @error {@link PollRequestFlow.UnexpectedMessageIdException}
  */

java/google/registry/model/poll/PollMessage.java

@@ -50,11 +50,30 @@ import google.registry.model.transfer.TransferResponse.DomainTransferResponse;
 import java.util.List;
 import org.joda.time.DateTime;
 
-/** A poll message that is pending for a registrar. */
+/**
+ * A poll message that is pending for a registrar.
+ *
+ * <p>Poll messages are not delivered until their {@link #eventTime} has passed. Poll messages can
+ * be speculatively enqueued for future delivery, and then modified or deleted before that date has
+ * passed. Unlike most other entities in Datastore, which are marked as deleted but otherwise
+ * retained for historical purposes, poll messages are truly deleted once they have been delivered
+ * and ACKed.
+ *
+ * <p>Poll messages are parented off of the {@link HistoryEntry} that resulted in their creation.
+ * This means that poll messages are contained in the Datastore entity group of the parent {@link
+ * EppResource} (which can be a domain, application, contact, or host). It is thus possible to
+ * perform a strongly consistent query to find all poll messages associated with a given EPP
+ * resource.
+ *
+ * <p>Poll messages are identified externally by registrars using the format defined in {@link
+ * PollMessageExternalKeyConverter}.
+ *
+ * @see "https://tools.ietf.org/html/rfc5730#section-2.9.2.3"
+ */
 @Entity
 @ExternalMessagingName("message")
-public abstract class PollMessage
-    extends ImmutableObject implements Buildable, TransferServerApproveEntity {
+public abstract class PollMessage extends ImmutableObject
+    implements Buildable, TransferServerApproveEntity {
 
 
   public static final Converter<Key<PollMessage>, String> EXTERNAL_KEY_CONVERTER =
@@ -158,7 +177,11 @@ public abstract class PollMessage
     }
   }
 
-  /** A one-time poll message. */
+  /**
+   * A one-time poll message.
+   *
+   * <p>One-time poll messages are deleted from Datastore once they have been delivered and ACKed.
+   */
   @EntitySubclass(index = false)
   public static class OneTime extends PollMessage {
 
@@ -252,7 +275,13 @@ public abstract class PollMessage
     }
   }
 
-  /** An autorenew poll message which recurs annually. */
+  /**
+   * An auto-renew poll message which recurs annually.
+   *
+   * <p>Auto-renew poll messages are not deleted until the registration of their parent domain has
+   * been canceled, because there will always be a speculative renewal for next year until that
+   * happens.
+   */
   @EntitySubclass(index = false)
   public static class Autorenew extends PollMessage {
 

java/google/registry/model/poll/PollMessageExternalKeyConverter.java

@@ -28,7 +28,8 @@ import google.registry.model.reporting.HistoryEntry;
 import java.util.List;
 
 /**
- * A converter between external key strings for PollMessages and Objectify Keys to the resource.
+ * A converter between external key strings for {@link PollMessage}s (i.e. what registrars use to
+ * identify and ACK them) and Datastore keys to the resource.
  *
  * <p>The format of the key string is A-B-C-D-E as follows:
  *