Issue #2687003 by alexpott, mikeryan, eojthebrave, xjm, benjy, quietone,...

Issue #2687003 by alexpott, mikeryan, eojthebrave, xjm, benjy, quietone, catch: Update migrate.api.php to reflect the current API

core/modules/migrate/migrate.api.php

@@ -17,33 +17,30 @@
  * @section overview Overview of migration
  * Migration is an
  * @link http://wikipedia.org/wiki/Extract,_transform,_load Extract, Transform, Load @endlink
- * (ETL) process. For historical reasons, in the Drupal migration tool the
- * extract phase is called "source", the transform phase is called "process",
- * and the load phase is called "destination".
+ * (ETL) process. In the Drupal migration API the extract phase is called
+ * "source", the transform phase is called "process", and the load phase is
+ * called "destination". It is important to understand that the "load" in ETL
+ * means to load data into storage, while traditionally Drupal uses "load" to
+ * mean load data from storage into memory.
  *
- * Source, process, and destination phases are each provided by plugins. Source
- * plugins extract data from a data source in "rows", containing "properties".
- * Each row is handed off to one or more series of process plugins, where each
- * series operates to transform the row data into one result property. After all
- * the properties are processed, the resulting row is handed off to a
- * destination plugin, which saves the data.
+ * Source, process, and destination phases are each provided by plugins.
+ * Source plugins extract data from a data source in "rows", containing
+ * "properties". Each row is handed off to one or more process plugins which
+ * transform the row's properties. After all the properties are processed, the
+ * resulting row is handed off to a destination plugin, which saves the data.
  *
- * The Migrate module provides process plugins for common operations (setting
- * default values, mapping values, etc.), and destination plugins for Drupal
- * core objects (configuration, entity, URL alias, etc.). The Migrate Drupal
- * module provides source plugins to extract data from various versions of
- * Drupal. Custom and contributed modules can provide additional plugins; see
- * the @link plugin_api Plugin API topic @endlink for generic information about
- * providing plugins, and sections below for details about the plugin types.
+ * A source plugin, one or more process plugins, and a destination plugin are
+ * brought together to extract, transform, and load (in the ETL sense) a specific
+ * type of data by a migration plugin.
  *
- * The configuration of migrations is stored in configuration entities, which
- * list the IDs and configurations of the plugins that are involved. See
- * @ref sec_entity below for details. To migrate an entire site, you'll need to
- * create a migration manifest; see @ref sec_manifest for details.
- *
- * https://www.drupal.org/node/2127611 has more complete information on the
- * Migration API, including information on load plugins, which are only used
- * in Drupal 6 migration.
+ * @section sec_migrations Migration plugins
+ * Migration plugin definitions are stored in a module's 'migrations' directory.
+ * For backwards compatibility we also scan the 'migration_templates' directory.
+ * Examples of migration plugin definitions can be found in
+ * 'core/modules/action/migration_templates'. The plugin class is
+ * \Drupal\migrate\Plugin\Migration, with interface
+ * \Drupal\migrate\Plugin\MigrationInterface. Migration plugins are managed by
+ * the \Drupal\migrate\Plugin\MigrationPluginManager class.
  *
  * @section sec_source Source plugins
  * Migration source plugins implement
@@ -61,7 +58,9 @@
  * with \Drupal\migrate\Annotation\MigrateProcessPlugin annotation, and must be
  * in namespace subdirectory Plugin\migrate\process under the namespace of the
  * module that defines them. Migration process plugins are managed by the
- * \Drupal\migrate\Plugin\MigratePluginManager class.
+ * \Drupal\migrate\Plugin\MigratePluginManager class. The Migrate module
+ * provides process plugins for common operations (setting default values,
+ * mapping values, etc.).
  *
  * @section sec_destination Destination plugins
  * Migration destination plugins implement
@@ -70,34 +69,12 @@
  * annotated with \Drupal\migrate\Annotation\MigrateDestination annotation, and
  * must be in namespace subdirectory Plugin\migrate\destination under the
  * namespace of the module that defines them. Migration destination plugins
- * are managed by the
- * \Drupal\migrate\Plugin\MigrateDestinationPluginManager class.
- *
- * @section sec_entity Migration configuration entities
- * The definition of how to migrate each type of data is stored in configuration
- * entities. The migration configuration entity class is
- * \Drupal\migrate\Entity\Migration, with interface
- * \Drupal\migrate\Entity\MigrationInterface; the configuration schema can be
- * found in the migrate.schema.yml file. Migration configuration consists of IDs
- * and configuration for the source, process, and destination plugins, as well
- * as information on dependencies. Process configuration consists of sections,
- * each of which defines the series of process plugins needed for one
- * destination property. You can find examples of migration configuration files
- * in the core/modules/migrate_drupal/config/install directory.
+ * are managed by the \Drupal\migrate\Plugin\MigrateDestinationPluginManager
+ * class. The Migrate module provides destination plugins for Drupal core
+ * objects (configuration and entity).
  *
- * @section sec_manifest Migration manifests
- * You can run a migration with the "drush migrate-manifest" command, providing
- * a migration manifest file. This file lists the configuration names of the
- * migrations you want to execute, as well as any dependencies they have (you
- * can find these in the "migration_dependencies" sections of the individual
- * configuration files). For example, to migrate blocks from a Drupal 6 site,
- * you would list:
- * @code
- * # Migrate blocks from Drupal 6 to 8
- * - d6_filter_format
- * - d6_custom_block
- * - d6_block
- * @endcode
+ * @section sec_more_info More information
+ * @link https://www.drupal.org/node/2127611 Migration API documentation. @endlink
  *
  * @see update_api
  * @}