Issue #2845484 by Jo Fitzgerald, quietone, Kifah Meeran, Winthropian,...

Issue #2845484 by Jo Fitzgerald, quietone, Kifah Meeran, Winthropian, phenaproxima, tstoeckler: Add documentation to MachineName process plugin

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

@@ -11,13 +11,28 @@
 use Symfony\Component\DependencyInjection\ContainerInterface;
 
 /**
- * This plugin creates a machine name.
+ * Creates a machine name.
  *
- * The current value gets transliterated, non-alphanumeric characters removed
- * and replaced by an underscore and multiple underscores are collapsed into
- * one.
+ * The machine_name process plugin takes the source value and runs it through
+ * the transliteration service. This makes the source value lowercase,
+ * replaces anything that is not a number or a letter with an underscore,
+ * and removes duplicate underscores.
  *
- * @link https://www.drupal.org/node/2135323 Online handbook documentation for machine_name process plugin @endlink
+ * Letters will have language decorations and accents removed.
+ *
+ * Example:
+ *
+ * @code
+ * process:
+ *   bar:
+ *     plugin: machine_name
+ *     source: foo
+ * @endcode
+ *
+ * If the value of foo in the source is 'áéí!' then the destination value of bar
+ * will be 'aei_'.
+ *
+ * @see \Drupal\migrate\Plugin\MigrateProcessInterface
  *
  * @MigrateProcessPlugin(
  *   id = "machine_name"