Add documentation to Flatten process plugin

Self-assigning for review.

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + * example array(array(1, 2, array(3, 4)), array(5), 6) becomes
   

   Let's convert from array() syntax to [] syntax.

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + * array(1, 2, 3, 4, 5, 6). During some types of processing (e.g. user permission
   

   This line is longer than 80 characters.

Taking a look at this issue as part of SprintWeekend2017

Updated array syntax

re-uploading the same patch file and interdiff as suggested in IRC. Also marking as Needs review. Looks like issue was not with this patch, but a more generic caching issue

Automated tests passed

Thanks for your work on this, @leslieg! Unfortunately, in re-reading the documentation, I see several wording problems that might confuse and befuddle (confuddle?) folks inexperienced in Migrate sorcery (which is absolutely not your fault, this is all copied-and-pasted from the handbook pages).

1. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + * example array[array[1, 2, array[3, 4]], array[5], 6] becomes
   

   The word "array" needs to be removed. Short array syntax is simply [5, 6], as opposed to array(5, 6). :)

2. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + * array[1, 2, 3, 4, 5, 6]. During some types of processing (e.g. user permission
   

   Nit: This line exceeds 80 characters. But then again, it will not once the word "array" is removed.

3. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + * splitting), what was once a single value gets transformed into multiple
   + * values. This plugin will flatten them back down to single values again.
   

   "what was once a single value gets transformed into multiple value." This is confusing. To me, "multiple values" means something like ['foo', 'bar', 'baz']. This phrasing implies that such a value will be converted from an array to a scalar, which is not the case.

   What we should say instead is that this will flatten a multidimensional array into a one-dimensional array. That would be consistent and easily explainable developer-friendly wording, IMHO.

4. +++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
   @@ -6,13 +6,39 @@
   + *      -
   + *        plugin: static_map
   + *        source: keywords
   + *        map:
   + *          foo: bar
   + *          baz:
   + *            - qux
   + *            - quux
   

   Let's change this to an example using the default_value plugin. Using static_map here means we need to explain, if only in a cursory fashion, what static_map is doing. default_value would be MUCH easier to grok in the context of this example.

Documentation tweaks in response to #14 and an additional conversion from array() to [].

Oops, missed the default_value plugin source.

Looking really good, except...

+++ b/core/modules/migrate/src/Plugin/migrate/process/Flatten.php
@@ -6,13 +6,35 @@
+ * In this example, items in the source field keywords are mapped to items for
+ * the destination field tags. Given [foo, baz] at the input, the static_map
+ * process results in [bar, [qux, quux]]. At this point, Migrate would try to
+ * import two items: bar and [qux, quux]. The latter is not a valid one and
+ * won't be imported. We need to pass the values through the flatten processor
+ * to obtain a three items array [bar, qux, quux], suitable for import.

This explanation no longer matches the actual code of the example :) Let's have the default_value plugin return a nested array of arbitrary scalar values to demonstrate.

Example rewritten.

I think this looks good-to-go.

-mike

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!

Test-bot error, returning to RTBC.

Committed and pushed 6ae744c to 8.4.x and 3115b5a to 8.3.x. Thanks!