Issue #2845490 by Jo Fitzgerald, wturrell, quietone, phenaproxima, xjm: Add...

Issue #2845490 by Jo Fitzgerald, wturrell, quietone, phenaproxima, xjm: Add documentation to Substr process plugin

(cherry picked from commit 6ebf68a2)

core/modules/migrate/src/Plugin/migrate/process/Substr.php

@@ -9,9 +9,44 @@
 use Drupal\Component\Utility\Unicode;
 
 /**
- * This plugin returns a substring of the current value.
+ * Returns a substring of the input value.
  *
- * @link https://www.drupal.org/node/2771965 Online handbook documentation for substr process plugin @endlink
+ * The substr process plugin returns the portion of the input value specified by
+ * the start and length parameters. This is a wrapper around the PHP substr()
+ * function.
+ *
+ * Available configuration keys:
+ * - start: (optional) The returned string will start this many characters after
+ *   the beginning of the string. Defaults to NULL.
+ * - length: (optional) The maximum number of characters in the returned
+ *   string. Defaults to NULL.
+ *
+ * If start is NULL and length is an integer, the start position is the
+ * beginning of the string. If start is an integer and length is NULL, the
+ * substring starting from the start position until the end of the string will
+ * be returned. If both start and length are NULL the entire string is returned.
+ *
+ * Example:
+ *
+ * @code
+ * process:
+ *   new_text_field:
+ *     plugin: substr
+ *     source: some_text_field
+ *       start: 6
+ *       length: 10
+ * @endcode
+ *
+ * If some_text_field was 'Marie Skłodowska Curie' then
+ * $destination['new_text_field'] would be 'Skłodowska'.
+ *
+ * The PHP equivalent of this is:
+ *
+ * @code
+ * $destination['new_text_field'] = substr($source['some_text_field'], 6, 10);
+ * @endcode
+ *
+ * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  *
  * @MigrateProcessPlugin(
  *   id = "substr"