Issue #3259471: Improve str_replace documentation re: regex (preg_replace)

src/Plugin/migrate/process/StrReplace.php

@@ -54,9 +54,12 @@ use Drupal\migrate\Row;
  * foo is "/[0-9]{3}/" in search and bar is "the" in replace, field_text will be
  * "vero eos et the accusam et justo the duo".
  *
- * All the rules for
+ * Depending on the value of 'regex', the rules for
  * @link http://php.net/manual/function.str-replace.php str_replace @endlink
- * apply. This means that you can provide arrays as values.
+ * or
+ * @link http://php.net/manual/function.preg-replace.php preg_replace @endlink
+ * apply. This means that you can provide arrays as values, your replace string
+ * can include backreferences, etc.
  *
  * Multiple values can be matched like this:
  * @code
@@ -67,6 +70,19 @@ use Drupal\migrate\Row;
  *   replace: ["Austria", "Switzerland", "Denmark"]
  * @endcode
  *
+ * Replace with a regex backreference like this:
+ * @code
+ * field_text:
+ *   plugin: str_replace
+ *   regex: true
+ *   source: text
+ *   search: foo
+ *   replace: bar
+ * @endcode
+ * If the value of text is "@username" in source,
+ * foo is "/@(\S+)/" in search and bar is "$1" in replace, field_text will be
+ * "username".
+ *
  * @codingStandardsIgnoreEnd
  */
 class StrReplace extends ProcessPluginBase {