diff --git a/core/modules/migrate/src/Plugin/migrate/process/Iterator.php b/core/modules/migrate/src/Plugin/migrate/process/Iterator.php
index d85abfd..adfd367 100644
--- a/core/modules/migrate/src/Plugin/migrate/process/Iterator.php
+++ b/core/modules/migrate/src/Plugin/migrate/process/Iterator.php
@@ -7,9 +7,82 @@
 use Drupal\migrate\Row;
 
 /**
- * This plugin iterates and processes an array.
+ * Iterates and processes an associative array.
  *
- * @link https://www.drupal.org/node/2135345 Online handbook documentation for iterator process plugin @endlink
+ * The iterator process plugin allows sub-processing of a list of associative
+ * arrays. Often source data will include multiple-value properties as
+ * associative arrays. For example, for file uploads on Drupal 6, the upload
+ * property contains a list of sub-properties.
+ *
+ * Available configuration keys:
+ *   - process: the plugin(s) that will process each element of the source.
+ *   - key: runs the process pipeline for the defined key.
+ *
+ * Examples:
+ *
+ * @code
+ * source: Array
+ * (
+ *   [upload] => Array
+ *     (
+ *       [0] => Array
+ *         (
+ *           [fid] => 1
+ *           [list] => 0
+ *           [description] => "File number 1"
+ *         )
+ *       [1] => Array
+ *         (
+ *           [fid] => 2
+ *           [list] => 1
+ *           [description] => "File number 2"
+ *         )
+ *     )
+ * )
+ * ...
+ * @endcode
+ *
+ * The iterator process plugin will take these arrays one at a time and run its
+ * own process over each one:
+ *
+ * @code
+ * process:
+ *   upload:
+ *     plugin: iterator
+ *     source: upload
+ *     process:
+ *       target_id:
+ *         plugin: migration_lookup
+ *         migration: d6_file
+ *         source: fid
+ *       display: list
+ *       description: description
+ * @endcode
+ *
+ * In this case, each item in the upload array will be processed bye the
+ * iterator process plugin. The target_id will be found by looking up the
+ * destination value from a previous migration. The display and description
+ * fields will simply be mapped.
+ *
+ * The mapping values passed to iterator are special. Numeric values may not be
+ * used.
+ *
+ * @code
+ *   field_relationship:
+       -
+         plugin: migration_lookup
+ *       migration:
+ *         - migration_page
+ *         - migration_blog
+ *       source: nid
+ *     -
+ *       plugin: iterator
+ *       process:
+ *         target_id: '0'
+ * @endcode
+ * In the migration above, the value mapped to target_id is intentionally '0'.
+ *
+ * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  *
  * @MigrateProcessPlugin(
  *   id = "iterator",