Issue #3203009 by quietone, Gauravmahlawat, joachim, catch: the methods in...

Issue #3203009 by quietone, Gauravmahlawat, joachim, catch: the methods in FieldableEntity should document how they are meant to be used

(cherry picked from commit 76f6b690)

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

@@ -21,6 +21,12 @@ abstract class FieldableEntity extends DrupalSqlBase {
   /**
    * Returns all non-deleted field instances attached to a specific entity type.
    *
+   * Typically, getFields() is used in the prepareRow method of a source plugin
+   * to get a list of all the field instances of the entity. A source plugin can
+   * then loop through the list of fields to do any other preparation before
+   * processing the row. Typically, a source plugin will use getFieldValues()
+   * to get the values of each field.
+   *
    * @param string $entity_type
    *   The entity type ID.
    * @param string|null $bundle
@@ -47,6 +53,9 @@ protected function getFields($entity_type, $bundle = NULL) {
   /**
    * Retrieves field values for a single field of a single entity.
    *
+   * Typically, getFieldValues() is used in the prepareRow method of a source
+   * plugin where the return values are placed on the row source.
+   *
    * @param string $entity_type
    *   The entity type.
    * @param string $field