[Connectors API] Unify class docs of the connector and sync job state machines (#105511)

x-pack/plugin/ent-search/src/main/java/org/elasticsearch/xpack/application/connector/ConnectorInvalidStatusTransitionException.java

@@ -10,10 +10,10 @@ package org.elasticsearch.xpack.application.connector;
 public class ConnectorInvalidStatusTransitionException extends Exception {
 
     /**
-     * Constructs an ConnectorInvalidStatusTransitionException exception with a detailed message.
+     * Constructs a {@link ConnectorInvalidStatusTransitionException} exception with a detailed message.
      *
-     * @param current The current state of the connector.
-     * @param next The attempted next state of the connector.
+     * @param current The current state of the {@link Connector}.
+     * @param next The attempted next state of the {@link Connector}.
      */
     public ConnectorInvalidStatusTransitionException(ConnectorStatus current, ConnectorStatus next) {
         super(

x-pack/plugin/ent-search/src/main/java/org/elasticsearch/xpack/application/connector/ConnectorStateMachine.java

@@ -13,9 +13,9 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * The {@link ConnectorStateMachine} class manages state transitions for connectors
+ * The {@link ConnectorStateMachine} class manages state transitions for instances of {@link Connector}
  * in accordance with the <a href="https://github.com/elastic/connectors/blob/main/docs/CONNECTOR_PROTOCOL.md">Connector Protocol</a>.
- * It defines valid transitions between different connector states and provides a method to validate these transitions.
+ * It defines valid transitions between instances of {@link ConnectorStatus} and provides a method to validate these transitions.
  */
 public class ConnectorStateMachine {
 
@@ -33,10 +33,10 @@ public class ConnectorStateMachine {
     );
 
     /**
-     * Checks if a transition from one connector state to another is valid.
+     * Checks if a transition from one {@link ConnectorStatus} to another is valid.
      *
-     * @param current The current state of the connector.
-     * @param next The proposed next state of the connector.
+     * @param current The current {@link ConnectorStatus} of the {@link Connector}.
+     * @param next The proposed next {@link ConnectorStatus} of the {@link Connector}.
      */
     public static boolean isValidTransition(ConnectorStatus current, ConnectorStatus next) {
         return validNextStates(current).contains(next);

x-pack/plugin/ent-search/src/main/java/org/elasticsearch/xpack/application/connector/syncjob/ConnectorSyncJobStateMachine.java

@@ -15,9 +15,9 @@ import java.util.Map;
 import java.util.Set;
 
 /**
- * The {@link ConnectorSyncJobStateMachine} class manages state transitions for sync jobs
+ * The {@link ConnectorSyncJobStateMachine} class manages state transitions for instances of {@link ConnectorSyncJob}
  * in accordance with the <a href="https://github.com/elastic/connectors/blob/main/docs/CONNECTOR_PROTOCOL.md">Connector Protocol</a>.
- * It defines valid transitions between different connector sync job states and provides a method to validate these transitions.
+ * It defines valid transitions between instances of {@link ConnectorSyncStatus} and provides a method to validate these transitions.
  */
 public class ConnectorSyncJobStateMachine {
 
@@ -39,10 +39,10 @@ public class ConnectorSyncJobStateMachine {
     );
 
     /**
-     * Checks if a transition from one connector sync job state to another is valid.
+     * Checks if a transition from one {@link ConnectorSyncStatus} to another is valid.
      *
-     * @param current The current state of the connector sync job.
-     * @param next The proposed next state of the connector sync job.
+     * @param current The current {@link ConnectorSyncStatus} of the {@link ConnectorSyncJob}.
+     * @param next The proposed next {link ConnectorSyncStatus} of the {@link ConnectorSyncJob}.
      */
     public static boolean isValidTransition(ConnectorSyncStatus current, ConnectorSyncStatus next) {
         return VALID_TRANSITIONS.getOrDefault(current, Collections.emptySet()).contains(next);