diff --git a/core/modules/migrate/src/Plugin/MigrateSourceInterface.php b/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
index ef1785e..d9f30c1 100644
--- a/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
+++ b/core/modules/migrate/src/Plugin/MigrateSourceInterface.php
@@ -53,8 +53,11 @@ public function __toString();
    *   An associative array of field definitions keyed by field ID. Values are
    *   associative arrays with a structure that contains the field type ('type'
    *   key). The other keys are the field storage settings as they are returned
-   *   by FieldStorageDefinitionInterface::getSettings(). As an example, for a
-   *   composite source primary key that is defined by an integer and a
+   *   by FieldStorageDefinitionInterface::getSettings().
+   *
+   *   Examples:
+   *
+   *   A composite source primary key that is defined by an integer and a
    *   string, the returned value might look like:
    *   @code
    *     return [
@@ -82,7 +85,9 @@ public function __toString();
    *   @endcode
    *   Additional custom keys/values, that are not part of field storage
    *   definition, can be passed in definitions. The most common setting, passed
-   *   along the ID definition, is 'alias' used by SqlBase source plugin:
+   *   along the ID definition, is 'alias' used by the SqlBase source plugin to
+   *   distinguish between ambiguous column names - for example, when a SQL
+   *   source query joins two tables with the same column names.
    *   @code
    *     return [
    *       'nid' => [