Add documentation to the LinkUri process plugin

Also, we should figure out and document (or fix) why the plugin expects an array and then only use the first item

This plugin was initially added in #2417793-13: Allow entity: URIs to be entered in link fields, but the issue thread does not focus on the plugin itself (initially called userpath_uri). I dug through all commits for the LinkUri process plugin, but as far as I can track down, there is no reason (and never was) to expect an array as input, and requiring it to be an array seems to be unintentional.

Patch attached that contains a first attempt at documenting the LinkUri plugin, while at the same time deprecating the option to pass in an array as source value. Not sure if this deprecation strategy is acceptable, or if the deprecation itself requires a test.

The documentation looks good, but this patch is making a lot of changes which are not related to the documentation at all. Those changes are fine and good, but they are out of scope for this issue. It'd be better to remove all non-documentation changes from the current patch, then open a separate issue to streamline the value handling.

Thanks @phenaproxima, I have opened #3031528: LinkUri source value should not be an array. to address the source value handling.

#3031528: LinkUri source value should not be an array. has landed, here is a patch with just the documentation changes from the patch in #5.

LGTM Thanks!

Looks like a testbot hiccup

Yes, really thanks!

I've got a few points though.

1. +++ b/core/modules/menu_link_content/src/Plugin/migrate/process/LinkUri.php
   @@ -12,9 +12,28 @@
   + *   values are ignored. Passing the source value as an array is deprecated.
   

   Documenting deprecated behaviour seems wrong to me. Is this normally done? I'd prefer it was removed

2. +++ b/core/modules/menu_link_content/src/Plugin/migrate/process/LinkUri.php
   @@ -12,9 +12,28 @@
   + * Examples:
   

   The example needs an explanation following it, after the @endcode. This was done for all the ones in migrate and we should keep up the practice.

3. +++ b/core/modules/menu_link_content/src/Plugin/migrate/process/LinkUri.php
   @@ -12,9 +12,28 @@
   + *   "link/uri":
   

   Remove the quotes, they are not needed

#13.1 Removed the documentation for the deprecated usage. The deprecated usage is already documented in the @trigger_error function:

    if (is_array($value)) {
      $value = reset($value);
      @trigger_error('Passing an array as source value into the link_uri migrate process plugin is deprecated in drupal:8.8.0. The possibility to pass an array as source value to the plugin will be removed in drupal:9.0.0. Pass a string value instead. See https://www.drupal.org/node/3043694', E_USER_DEPRECATED);
    }

#13.2 Added an explanation with an example entry, similar to for example \Drupal\migrate\Plugin\migrate\process\Concat

#13.3 Removed the quotes.

Fixed the magically changing node id.

@quietone's review from #13 has been address, this looks RTBC to me.

All looks good so setting back to RTBC! Tests failure is not related (see #3055648: Frequent random fail in \Drupal\Tests\media_library\FunctionalJavascript\MediaLibraryTest).

Same random failure as mentioned in #18.

Somebody get testbot a glass of water!

Committed fdccb84 and pushed to 8.8.x. Thanks!