Add documentation to Extract process plugin

Self-assigning for review.

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + * Extracts a value from the source value array.
   

   s/source value/input

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + * The extract process plugin is used to pull data from potentially multi-level
   + * arrays in the source. One use case is extracting data from field arrays in
   

   I'd rather this said "from an input array, which may have multiple levels."

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + * Available configuration keys
   

   Needs to end with a colon.

4. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + *   - source: The source value.
   

   Can this just say "the input value"?

5. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + *   - index: An array of indices.
   

   This needs to be better explained.

6. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + *   - default: (optional) A default value to assing to the destination if the key does not exist.
   

   This line should not exceed 80 characters.

7. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -21,7 +63,22 @@
   -   * {@inheritdoc}
   +   * Performs the associated process.
   +   *
   +   * @param string $value
   +   *   The input string.
   +   * @param \Drupal\migrate\MigrateExecutableInterface $migrate_executable
   +   *   The migration in which this process is being executed.
   +   * @param \Drupal\migrate\Row $row
   +   *   The row from the source to process.
   +   * @param string $destination_property
   +   *   The destination property currently worked on. This is only used together
   +   *   with the $row above.
   +   *
   +   * @return string
   +   *   The sub string of $value.
   +   *
   +   * @throws \Drupal\migrate\MigrateException
   

   This should just be @inheritdoc.

I added all changes suggested by @phenaproxima and also fixed a typo I found at #6 ("assing").

Very close now.

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + * Extracts a value from the input array.
   

   Let's change this to "Extracts a value from an array."

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + * may have multiple levels. One use case is extracting data from field arrays in
   

   Nit: Exceeds 80 characters.

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + * previous versions of Drupal - for example, in Drupal 7 a field array would be
   

   This is phrased awkwardly. I'd prefer something like "For instance, in Drupal 7, a field array would be indexed first by language, then by delta, then finally a key such as 'value'."

4. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + *   - source: The input value.
   

   Let's mention that this must be an array.

5. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + * In addition, there is a default configuration option for this plugin. When a
   

   This first sentence is redundant. Let's ice it.

6. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,52 @@
   + * default is specified, if the key doesn't exist, then the plugin will return
   

   More weird phrasing. Can it say "If a default value is specified, it will be returned if the index does not exist in the input array"?

Documentation tweaks in response to #7.

I love it. Looks fantastic.

Straightforward code documentation improvements can always go into any patch release, alpha, beta, or RC, so please always file them against the production branch (currently 8.3.x). Thanks!

Random CI failure.

Overall this documentation reads very well. Just some coding standards fixes and small typos:

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + *   - source: The input value - must be an array.
   + *   - index: The array of keys to access the value.
   + *   - default: (optional) A default value to assign to the destination if the
   + *      key does not exist.
   

   There is misformatting here where the array is indented, but the hyphens of the list should line up with the paragraph above. Also, the line with "key" is indented by one space too many.

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
   @@ -9,9 +9,51 @@
   + * $destination['new_text_field'] = $source['some_text_field']['und'][0]['value'].
   

   This should also be in @code tags, and the period at the end is not syntactically correct for PHP :)

Thanks everyone!

Fixed the issues stated in #13

+++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
@@ -9,9 +9,52 @@
+ *   plugin: extract

This line needs to be indented two spaces, but that can be fixed on commit. Looks good to me otherwise.

@Kifah Meeran, when you update patches, please be sure to provide an interdiff: https://www.drupal.org/documentation/git/interdiff

Here is an interdiff between #8 and #14.

+++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
@@ -37,8 +37,9 @@
+ * $destination['new_text_field'] = $source['some_text_field']['und'][0]['value']

The semicolon is still missing here. :) But I can add that on commit as well. Here are the changes I made on commit:

diff --git a/core/modules/migrate/src/Plugin/migrate/process/Extract.php b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
index c5bc450d23..544c306c50 100644
--- a/core/modules/migrate/src/Plugin/migrate/process/Extract.php
+++ b/core/modules/migrate/src/Plugin/migrate/process/Extract.php
@@ -28,7 +28,7 @@
  * @code
  * process:
  *   new_text_field:
- *   plugin: extract
+ *     plugin: extract
  *     source: some_text_field
  *     index:
  *       - und
@@ -38,7 +38,7 @@
  *
  * The PHP equivalent of this would be:
  * @code
- * $destination['new_text_field'] = $source['some_text_field']['und'][0]['value']
+ * $destination['new_text_field'] = $source['some_text_field']['und'][0]['value'];
  * @endcode
  * If a default value is specified, it will be returned if the index does not
  * exist in the input array.

Committed to 8.4.x and 8.3.x. Thanks everyone; good to see this documentation being added!