Add javadoc to contact/host flows and mark them final

Also make minor javadoc tweaks to domain transfer flows
to match what we are changing in contact/host flows.

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

java/google/registry/flows/contact/ContactCheckFlow.java

@@ -35,9 +35,11 @@ import javax.inject.Inject;
 /**
  * An EPP flow that checks whether a contact can be provisioned.
  *
+ * <p>This flows can check the existence of multiple contacts simultaneously.
+ *
  * @error {@link google.registry.flows.exceptions.TooManyResourceChecksException}
  */
-public class ContactCheckFlow extends LoggedInFlow {
+public final class ContactCheckFlow extends LoggedInFlow {
 
   @Inject ResourceCommand resourceCommand;
   @Inject @Config("maxChecks") int maxChecks;

java/google/registry/flows/contact/ContactCreateFlow.java

@@ -41,13 +41,13 @@ import google.registry.model.reporting.HistoryEntry;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that creates a new contact resource.
+ * An EPP flow that creates a new contact.
  *
  * @error {@link google.registry.flows.exceptions.ResourceAlreadyExistsException}
  * @error {@link ContactFlowUtils.BadInternationalizedPostalInfoException}
  * @error {@link ContactFlowUtils.DeclineContactDisclosureFieldDisallowedPolicyException}
  */
-public class ContactCreateFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactCreateFlow extends LoggedInFlow implements TransactionalFlow {
 
   @Inject ResourceCommand resourceCommand;
   @Inject @ClientId String clientId;

java/google/registry/flows/contact/ContactDeleteFlow.java

@@ -44,14 +44,21 @@ import javax.inject.Inject;
 import org.joda.time.Duration;
 
 /**
- * An EPP flow that deletes a contact resource.
+/**
+ * An EPP flow that deletes a contact.
+ *
+ * <p>Contacts that are in use by any domain cannot be deleted. The flow may return immediately if a
+ * quick smoke check determines that deletion is impossible due to an existing reference. However, a
+ * successful delete will always be asynchronous, as all existing domains must be checked for
+ * references to the host before the deletion is allowed to proceed. A poll message will be written
+ * with the success or failure message when the process is complete.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.ResourceNotOwnedException}
  * @error {@link google.registry.flows.exceptions.ResourceStatusProhibitsOperationException}
  * @error {@link google.registry.flows.exceptions.ResourceToDeleteIsReferencedException}
  * @error {@link google.registry.flows.exceptions.ResourceToMutateDoesNotExistException}
  */
-public class ContactDeleteFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactDeleteFlow extends LoggedInFlow implements TransactionalFlow {
 
   private static final ImmutableSet<StatusValue> DISALLOWED_STATUSES = ImmutableSet.of(
       StatusValue.LINKED,

java/google/registry/flows/contact/ContactInfoFlow.java

@@ -29,11 +29,15 @@ import google.registry.model.eppoutput.EppOutput;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that reads a contact.
+ * An EPP flow that returns information about a contact.
+ *
+ * <p>The response includes the contact's postal info, phone numbers, emails, the authInfo which can
+ * be used to request a transfer and the details of the contact's most recent transfer if it has
+ * ever been transferred. Any registrar can see any contact's information.
  *
  * @error {@link google.registry.flows.exceptions.ResourceToQueryDoesNotExistException}
  */
-public class ContactInfoFlow extends LoggedInFlow {
+public final class ContactInfoFlow extends LoggedInFlow {
 
   @Inject @TargetId String targetId;
   @Inject Optional<AuthInfo> authInfo;

java/google/registry/flows/contact/ContactTransferApproveFlow.java

@@ -43,14 +43,20 @@ import google.registry.model.transfer.TransferStatus;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that approves a pending transfer on a {@link ContactResource}.
+/**
+ * An EPP flow that approves a pending transfer on a contact.
+ *
+ * <p>The "gaining" registrar requests a transfer from the "losing" (aka current) registrar. The
+ * losing registrar has a "transfer" time period to respond (by default five days) after which the
+ * transfer is automatically approved. Within that window, this flow allows the losing client to
+ * explicitly approve the transfer request, which then becomes effective immediately.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.BadAuthInfoForResourceException}
  * @error {@link google.registry.flows.ResourceFlowUtils.ResourceNotOwnedException}
  * @error {@link google.registry.flows.exceptions.NotPendingTransferException}
  * @error {@link google.registry.flows.exceptions.ResourceToMutateDoesNotExistException}
  */
-public class ContactTransferApproveFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactTransferApproveFlow extends LoggedInFlow implements TransactionalFlow {
 
   @Inject ResourceCommand resourceCommand;
   @Inject @ClientId String clientId;
@@ -64,6 +70,10 @@ public class ContactTransferApproveFlow extends LoggedInFlow implements Transact
     registerExtensions(MetadataExtension.class);
   }
 
+  /**
+   * <p>The logic in this flow, which handles client approvals, very closely parallels the logic in
+   * {@link ContactResource#cloneProjectedAtTime} which handles implicit server approvals.
+   */
   @Override
   public final EppOutput run() throws EppException {
     ContactResource existingContact = loadResourceToMutate(ContactResource.class, targetId, now);

java/google/registry/flows/contact/ContactTransferCancelFlow.java

@@ -43,14 +43,20 @@ import google.registry.model.transfer.TransferStatus;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that cancels a pending transfer on a {@link ContactResource}.
+/**
+ * An EPP flow that cancels a pending transfer on a contact.
+ *
+ * <p>The "gaining" registrar requests a transfer from the "losing" (aka current) registrar. The
+ * losing registrar has a "transfer" time period to respond (by default five days) after which the
+ * transfer is automatically approved. Within that window, this flow allows the gaining client to
+ * withdraw the transfer request.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.BadAuthInfoForResourceException}
  * @error {@link google.registry.flows.exceptions.NotPendingTransferException}
  * @error {@link google.registry.flows.exceptions.NotTransferInitiatorException}
  * @error {@link google.registry.flows.exceptions.ResourceToMutateDoesNotExistException}
  */
-public class ContactTransferCancelFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactTransferCancelFlow extends LoggedInFlow implements TransactionalFlow {
 
   @Inject ResourceCommand resourceCommand;
   @Inject Optional<AuthInfo> authInfo;

java/google/registry/flows/contact/ContactTransferQueryFlow.java

@@ -32,14 +32,21 @@ import google.registry.model.eppoutput.EppOutput;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that queries a pending transfer on a {@link ContactResource}.
+ * An EPP flow that queries a pending transfer on a contact.
+ *
+ * <p>The "gaining" registrar requests a transfer from the "losing" (aka current) registrar. The
+ * losing registrar has a "transfer" time period to respond (by default five days) after which the
+ * transfer is automatically approved. This flow can be used by the gaining or losing registrars
+ * (or anyone with the correct authId) to see the status of a transfer, which may still be pending
+ * or may have been approved, rejected, cancelled or implicitly approved by virtue of the transfer
+ * period expiring.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.BadAuthInfoForResourceException}
  * @error {@link google.registry.flows.exceptions.NoTransferHistoryToQueryException}
  * @error {@link google.registry.flows.exceptions.NotAuthorizedToViewTransferException}
  * @error {@link google.registry.flows.exceptions.ResourceToQueryDoesNotExistException}
  */
-public class ContactTransferQueryFlow extends LoggedInFlow {
+public final class ContactTransferQueryFlow extends LoggedInFlow {
 
   @Inject Optional<AuthInfo> authInfo;
   @Inject @ClientId String clientId;

java/google/registry/flows/contact/ContactTransferRejectFlow.java

@@ -42,14 +42,19 @@ import google.registry.model.transfer.TransferStatus;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that rejects a pending transfer on a {@link ContactResource}.
+ * An EPP flow that rejects a pending transfer on a contact.
+ *
+ * <p>The "gaining" registrar requests a transfer from the "losing" (aka current) registrar. The
+ * losing registrar has a "transfer" time period to respond (by default five days) after which the
+ * transfer is automatically approved. Within that window, this flow allows the losing client to
+ * reject the transfer request.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.BadAuthInfoForResourceException}
  * @error {@link google.registry.flows.ResourceFlowUtils.ResourceNotOwnedException}
  * @error {@link google.registry.flows.exceptions.NotPendingTransferException}
  * @error {@link google.registry.flows.exceptions.ResourceToMutateDoesNotExistException}
  */
-public class ContactTransferRejectFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactTransferRejectFlow extends LoggedInFlow implements TransactionalFlow {
 
   @Inject Optional<AuthInfo> authInfo;
   @Inject @ClientId String clientId;

java/google/registry/flows/contact/ContactTransferRequestFlow.java

@@ -48,7 +48,14 @@ import org.joda.time.DateTime;
 import org.joda.time.Duration;
 
 /**
- * An EPP flow that requests a transfer on a {@link ContactResource}.
+/**
+ * An EPP flow that requests a transfer on a contact.
+ *
+ * <p>The "gaining" registrar requests a transfer from the "losing" (aka current) registrar. The
+ * losing registrar has a "transfer" time period to respond (by default five days) after which the
+ * transfer is automatically approved. Within that window, the transfer might be approved explicitly
+ * by the losing registrar or rejected, and the gaining registrar can also cancel the transfer
+ * request.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.BadAuthInfoForResourceException}
  * @error {@link google.registry.flows.exceptions.ResourceToMutateDoesNotExistException}
@@ -56,7 +63,7 @@ import org.joda.time.Duration;
  * @error {@link google.registry.flows.exceptions.MissingTransferRequestAuthInfoException}
  * @error {@link google.registry.flows.exceptions.ObjectAlreadySponsoredException}
  */
-public class ContactTransferRequestFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactTransferRequestFlow extends LoggedInFlow implements TransactionalFlow {
 
   private static final ImmutableSet<StatusValue> DISALLOWED_STATUSES = ImmutableSet.of(
       StatusValue.CLIENT_TRANSFER_PROHIBITED,

java/google/registry/flows/contact/ContactUpdateFlow.java

@@ -48,7 +48,7 @@ import google.registry.model.reporting.HistoryEntry;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that updates a contact resource.
+ * An EPP flow that updates a contact.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.ResourceNotOwnedException}
  * @error {@link google.registry.flows.exceptions.AddRemoveSameValueEppException}
@@ -59,7 +59,7 @@ import javax.inject.Inject;
  * @error {@link ContactFlowUtils.BadInternationalizedPostalInfoException}
  * @error {@link ContactFlowUtils.DeclineContactDisclosureFieldDisallowedPolicyException}
  */
-public class ContactUpdateFlow extends LoggedInFlow implements TransactionalFlow {
+public final class ContactUpdateFlow extends LoggedInFlow implements TransactionalFlow {
 
   /**
    * Note that CLIENT_UPDATE_PROHIBITED is intentionally not in this list. This is because it