diff --git a/core/modules/migrate/src/Plugin/migrate/process/MachineName.php b/core/modules/migrate/src/Plugin/migrate/process/MachineName.php
index 15ed356..412eeb5 100644
--- a/core/modules/migrate/src/Plugin/migrate/process/MachineName.php
+++ b/core/modules/migrate/src/Plugin/migrate/process/MachineName.php
@@ -11,13 +11,26 @@
 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, runs it over the
+ * transliteration service, lowercases it, replaces anything that's not a number
+ * or a letter with an underscore and removes duplicate underscores. It's very
+ * often followed by one of the deduplication plugins.
  *
- * @link https://www.drupal.org/node/2135323 Online handbook documentation for machine_name process plugin @endlink
+ * 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"