Issue #2316413 by benjy, chx: Clean up MigrationInterface docs

core/modules/migrate/src/Entity/MigrationInterface.php

@@ -14,46 +14,96 @@
  */
 interface MigrationInterface extends ConfigEntityInterface {
 
+  /**
+   * A constant used for systemOfRecord.
+   */
   const SOURCE = 'source';
+
+  /**
+   * A constant used for systemOfRecord.
+   */
   const DESTINATION = 'destination';
 
   /**
-   * Codes representing the current status of a migration, and stored in the
-   * migrate_status table.
+   * The migration is currently not running.
    */
   const STATUS_IDLE = 0;
+
+  /**
+   * The migration is currently importing.
+   */
   const STATUS_IMPORTING = 1;
+
+  /**
+   * The migration is currently being rolled back.
+   */
   const STATUS_ROLLING_BACK = 2;
+
+  /**
+   * The migration is being stopped.
+   */
   const STATUS_STOPPING = 3;
+
+  /**
+   * The migration has been disabled.
+   */
   const STATUS_DISABLED = 4;
 
   /**
-   * Message types to be passed to saveMessage() and saved in message tables.
-   * MESSAGE_INFORMATIONAL represents a condition that did not prevent the
-   * operation from succeeding - all others represent different severities of
-   * conditions resulting in a source record not being imported.
+   * Migration error.
    */
   const MESSAGE_ERROR = 1;
+
+  /**
+   * Migration warning.
+   */
   const MESSAGE_WARNING = 2;
+
+  /**
+   * Migration notice.
+   */
   const MESSAGE_NOTICE = 3;
+
+  /**
+   * Migration info.
+   */
   const MESSAGE_INFORMATIONAL = 4;
 
   /**
-   * Codes representing the result of a rollback or import process.
+   * All records have been processed.
+   */
+  const RESULT_COMPLETED = 1;
+
+  /**
+   * The process has stopped itself (e.g., the memory limit is approaching).
+   */
+  const RESULT_INCOMPLETE = 2;
+
+  /**
+   * The process was stopped externally (e.g., via drush migrate-stop).
+   */
+  const RESULT_STOPPED = 3;
+
+  /**
+   * The process had a fatal error.
+   */
+  const RESULT_FAILED = 4;
+
+  /**
+   * Dependencies are unfulfilled - skip the process.
+   */
+  const RESULT_SKIPPED = 5;
+
+  /**
+   * This migration is disabled, skipping.
    */
-  const RESULT_COMPLETED = 1;   // All records have been processed
-  const RESULT_INCOMPLETE = 2;  // The process has interrupted itself (e.g., the
-                                // memory limit is approaching)
-  const RESULT_STOPPED = 3;     // The process was stopped externally (e.g., via
-                                // drush migrate-stop)
-  const RESULT_FAILED = 4;      // The process had a fatal error
-  const RESULT_SKIPPED = 5;     // Dependencies are unfulfilled - skip the process
-  const RESULT_DISABLED = 6;    // This migration is disabled, skipping
+  const RESULT_DISABLED = 6;
 
   /**
    * Returns the initialized source plugin.
    *
    * @return \Drupal\migrate\Plugin\MigrateSourceInterface
+   *   The source plugin.
    */
   public function getSourcePlugin();
 
@@ -73,6 +123,7 @@ public function getProcessPlugins(array $process = NULL);
    * Returns the initialized destination plugin.
    *
    * @return \Drupal\migrate\Plugin\MigrateDestinationInterface
+   *   The destination plugin.
    */
   public function getDestinationPlugin();
 
@@ -80,6 +131,7 @@ public function getDestinationPlugin();
    * Returns the initialized id_map plugin.
    *
    * @return \Drupal\migrate\Plugin\MigrateIdMapInterface
+   *   The ID map.
    */
   public function getIdMap();
 
@@ -91,6 +143,7 @@ public function getIdMap();
    * imported.
    *
    * @return int
+   *   A Unix timestamp representing the highwater mark.
    */
   public function getHighwater();