Issue #3204986 by Matroskeen, quietone: Add documentation for d7 field source plugins

core/modules/field/src/Plugin/migrate/source/d7/Field.php

@@ -8,6 +8,14 @@
 /**
  * Drupal 7 field source from database.
  *
+ * If the Drupal 7 Title module is enabled, the fields it provides are not
+ * migrated. The values of those fields will be migrated to the base fields they
+ * were replacing.
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
+ *
  * @MigrateSource(
  *   id = "d7_field",
  *   source_module = "field_sql_storage"
@@ -29,9 +37,7 @@ public function query() {
       ->condition('fci.deleted', 0);
     $query->join('field_config_instance', 'fci', '[fc].[id] = [fci].[field_id]');
 
-    // If the Drupal 7 Title module is enabled, we don't want to migrate the
-    // fields it provides. The values of those fields will be migrated to the
-    // base fields they were replacing.
+    // The Title module fields are not migrated.
     if ($this->moduleExists('title')) {
       $title_fields = [
         'title_field',

core/modules/field/src/Plugin/migrate/source/d7/FieldInstance.php

@@ -8,6 +8,43 @@
 /**
  * Drupal 7 field instances source from database.
  *
+ * If the Drupal 7 Title module is enabled, the fields it provides are not
+ * migrated. The values of those fields will be migrated to the base fields they
+ * were replacing.
+ *
+ * Available configuration keys:
+ *  - entity_type: (optional) The entity type (machine name) to filter field
+ *    instances retrieved from the source. If omitted, all field instances are
+ *    retrieved.
+ *  - bundle: (optional) The bundle machine name to filter field instances
+ *    retrieved from the source. It should be used in combination with
+ *    entity_type property and will be ignored otherwise.
+ *
+ * Examples:
+ *
+ * @code
+ * source:
+ *   plugin: d7_field_instance
+ *   entity_type: node
+ * @endcode
+ *
+ * In this example field instances of node entity type are retrieved from the
+ * source database.
+ *
+ * @code
+ * source:
+ *   plugin: d7_field_instance
+ *   entity_type: node
+ *   bundle: page
+ * @endcode
+ *
+ * In this example field instances of page content type are retrieved from the
+ * source database.
+ *
+ * For additional configuration keys, refer to the parent classes:
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
+ *
  * @MigrateSource(
  *   id = "d7_field_instance",
  *   source_module = "field"
@@ -37,9 +74,7 @@ public function query() {
       }
     }
 
-    // If the Drupal 7 Title module is enabled, we don't want to migrate the
-    // fields it provides. The values of those fields will be migrated to the
-    // base fields they were replacing.
+    // The Title module fields are not migrated.
     if ($this->moduleExists('title')) {
       $title_fields = [
         'title_field',

core/modules/field/src/Plugin/migrate/source/d7/FieldInstancePerFormDisplay.php

@@ -3,7 +3,12 @@
 namespace Drupal\field\Plugin\migrate\source\d7;
 
 /**
- * The field instance per form display source class.
+ * Drupal 7 field instance per form display source from database.
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\field\Plugin\migrate\source\d7\FieldInstance
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  *
  * @MigrateSource(
  *   id = "d7_field_instance_per_form_display",

core/modules/field/src/Plugin/migrate/source/d7/FieldInstancePerViewMode.php

@@ -3,7 +3,12 @@
 namespace Drupal\field\Plugin\migrate\source\d7;
 
 /**
- * The field instance per view mode source class.
+ * Drupal 7 field instance per view mode source class.
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\field\Plugin\migrate\source\d7\FieldInstance
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  *
  * @MigrateSource(
  *   id = "d7_field_instance_per_view_mode",

core/modules/field/src/Plugin/migrate/source/d7/FieldLabelDescriptionTranslation.php

@@ -5,7 +5,11 @@
 use Drupal\migrate_drupal\Plugin\migrate\source\DrupalSqlBase;
 
 /**
- * Gets field label and description translations.
+ * Drupal 7 i18n field label and description source from database.
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  *
  * @MigrateSource(
  *   id = "d7_field_instance_label_description_translation",

core/modules/field/src/Plugin/migrate/source/d7/FieldOptionTranslation.php

@@ -3,7 +3,11 @@
 namespace Drupal\field\Plugin\migrate\source\d7;
 
 /**
- * Gets field option label translations.
+ * Drupal 7 i18n field option label source from database.
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  *
  * @MigrateSource(
  *   id = "d7_field_option_translation",

core/modules/migrate_drupal/src/Plugin/migrate/source/d7/FieldableEntity.php

@@ -7,6 +7,14 @@
 /**
  * Base class for D7 source plugins which need to collect field values from
  * the Field API.
+ *
+ * Refer to the existing implementations for examples:
+ * @see \Drupal\node\Plugin\migrate\source\d7\Node
+ * @see \Drupal\user\Plugin\migrate\source\d7\User
+ *
+ * For available configuration keys, refer to the parent classes:
+ * @see \Drupal\migrate\Plugin\migrate\source\SqlBase
+ * @see \Drupal\migrate\Plugin\migrate\source\SourcePluginBase
  */
 abstract class FieldableEntity extends DrupalSqlBase {