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/host/HostCheckFlow.java

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

java/google/registry/flows/host/HostCreateFlow.java

@@ -51,7 +51,13 @@ import google.registry.model.reporting.HistoryEntry;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that creates a new host resource.
+ * An EPP flow that creates a new host.
+ *
+ * <p>Hosts can be "external", or "internal" (also known as "in bailiwick"). Internal hosts are
+ * those that are under a top level domain within this registry, and external hosts are all other
+ * hosts. Internal hosts must have at least one ip address associated with them, whereas external
+ * hosts cannot have any. This flow allows creating a host name, and if necessary enqueues tasks to
+ * update DNS.
  *
  * @error {@link google.registry.flows.EppXmlTransformer.IpAddressVersionMismatchException}
  * @error {@link google.registry.flows.exceptions.ResourceAlreadyExistsException}
@@ -62,7 +68,7 @@ import javax.inject.Inject;
  * @error {@link SubordinateHostMustHaveIpException}
  * @error {@link UnexpectedExternalHostIpException}
  */
-public class HostCreateFlow extends LoggedInFlow implements TransactionalFlow {
+public final class HostCreateFlow extends LoggedInFlow implements TransactionalFlow {
 
   @Inject ResourceCommand resourceCommand;
   @Inject @ClientId String clientId;

java/google/registry/flows/host/HostDeleteFlow.java

@@ -42,14 +42,20 @@ import google.registry.model.reporting.HistoryEntry;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that deletes a host resource.
+ * An EPP flow that deletes a host.
+ *
+ * <p>Hosts 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.ResourceToMutateDoesNotExistException}
  * @error {@link google.registry.flows.exceptions.ResourceToDeleteIsReferencedException}
  */
-public class HostDeleteFlow extends LoggedInFlow implements TransactionalFlow {
+public final class HostDeleteFlow extends LoggedInFlow implements TransactionalFlow {
 
   private static final ImmutableSet<StatusValue> DISALLOWED_STATUSES = ImmutableSet.of(
       StatusValue.LINKED,

java/google/registry/flows/host/HostInfoFlow.java

@@ -29,11 +29,14 @@ import google.registry.model.host.HostResource;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that reads a host.
+ * An EPP flow that returns information about a host.
+ *
+ * <p>The returned information included IP addresses, if any, and details of the host's most recent
+ * transfer if it has ever been transferred. Any registrar can see the information for any host.
  *
  * @error {@link google.registry.flows.exceptions.ResourceToQueryDoesNotExistException}
  */
-public class HostInfoFlow extends LoggedInFlow {
+public final class HostInfoFlow extends LoggedInFlow {
 
   @Inject @TargetId String targetId;
   @Inject Optional<AuthInfo> authInfo;

java/google/registry/flows/host/HostUpdateFlow.java

@@ -62,7 +62,17 @@ import java.util.Objects;
 import javax.inject.Inject;
 
 /**
- * An EPP flow that updates a host resource.
+ * An EPP flow that updates a host.
+ *
+ * <p>Hosts can be "external", or "internal" (also known as "in bailiwick"). Internal hosts are
+ * those that are under a top level domain within this registry, and external hosts are all other
+ * hosts. Internal hosts must have at least one IP address associated with them, whereas external
+ * hosts cannot have any.
+ *
+ * <p>This flow allows changing a host name, and adding or removing IP addresses to hosts. When
+ * a host is renamed from internal to external all IP addresses must be simultaneously removed, and
+ * when it is renamed from external to internal at least one must be added. If the host is renamed
+ * or IP addresses are added, tasks are enqueued to update DNS accordingly.
  *
  * @error {@link google.registry.flows.ResourceFlowUtils.ResourceNotOwnedException}
  * @error {@link google.registry.flows.exceptions.ResourceHasClientUpdateProhibitedException}
@@ -78,7 +88,7 @@ import javax.inject.Inject;
  * @error {@link RenameHostToExternalRemoveIpException}
  * @error {@link RenameHostToSubordinateRequiresIpException}
  */
-public class HostUpdateFlow extends LoggedInFlow implements TransactionalFlow {
+public final class HostUpdateFlow extends LoggedInFlow implements TransactionalFlow {
 
   /**
    * Note that CLIENT_UPDATE_PROHIBITED is intentionally not in this list. This is because it
@@ -260,33 +270,33 @@ public class HostUpdateFlow extends LoggedInFlow implements TransactionalFlow {
     }
   }
 
-  /** Cannot add ip addresses to an external host. */
+  /** Cannot add IP addresses to an external host. */
   static class CannotAddIpToExternalHostException extends ParameterValueRangeErrorException {
     public CannotAddIpToExternalHostException() {
-      super("Cannot add ip addresses to external hosts");
+      super("Cannot add IP addresses to external hosts");
     }
   }
 
-  /** Cannot remove all ip addresses from a subordinate host. */
+  /** Cannot remove all IP addresses from a subordinate host. */
   static class CannotRemoveSubordinateHostLastIpException
       extends StatusProhibitsOperationException {
     public CannotRemoveSubordinateHostLastIpException() {
-      super("Cannot remove all ip addresses from a subordinate host");
+      super("Cannot remove all IP addresses from a subordinate host");
     }
   }
 
-  /** Host rename from external to subordinate must also add an ip addresses. */
+  /** Host rename from external to subordinate must also add an IP addresses. */
   static class RenameHostToSubordinateRequiresIpException
       extends RequiredParameterMissingException {
     public RenameHostToSubordinateRequiresIpException() {
-      super("Host rename from external to subordinate must also add an ip address");
+      super("Host rename from external to subordinate must also add an IP address");
     }
   }
 
-  /** Host rename from subordinate to external must also remove all ip addresses. */
+  /** Host rename from subordinate to external must also remove all IP addresses. */
   static class RenameHostToExternalRemoveIpException extends ParameterValueRangeErrorException {
     public RenameHostToExternalRemoveIpException() {
-      super("Host rename from subordinate to external must also remove all ip addresses");
+      super("Host rename from subordinate to external must also remove all IP addresses");
     }
   }
 }