diff --git a/core/lib/Drupal/Core/Plugin/PluginFormInterface.php b/core/lib/Drupal/Core/Plugin/PluginFormInterface.php
index 9fb3ad5..e02dba6 100644
--- a/core/lib/Drupal/Core/Plugin/PluginFormInterface.php
+++ b/core/lib/Drupal/Core/Plugin/PluginFormInterface.php
@@ -10,18 +10,7 @@
 use Drupal\Core\Form\FormStateInterface;
 
 /**
- * Provides an interface for a plugin that contains a form.
- *
- * Plugin forms are usually contained in other forms. In order to know where the
- * plugin form is located in the parent form, #parents and #array_parents must
- * be known, but these are not available during the initial build phase. In
- * order to have these properties available when building the plugin form's
- * elements, let buildConfigurationForm() return a form element that has a
- * #process callback and build the rest of the form in the callback. By the time
- * the callback is executed, the element's #parents and #array_parents
- * properties will have been set by the form API. For more documentation on
- * #parents and #array_parents, see
- * https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/8.
+ * Provides an interface for an embeddable plugin form.
  *
  * @ingroup plugin_api
  */
@@ -30,10 +19,21 @@
   /**
    * Form constructor.
    *
+   * Plugin forms are embedded in other forms. In order to know where the plugin
+   * form is located in the parent form, #parents and #array_parents must be
+   * known, but these are not available during the initial build phase. In order
+   * to have these properties available when building the plugin form's
+   * elements, let this method return a form element that has a #process
+   * callback and build the rest of the form in the callback. By the time the
+   * callback is executed, the element's #parents and #array_parents properties
+   * will have been set by the form API. For more documentation on #parents and
+   * #array_parents, see
+   * https://api.drupal.org/api/drupal/developer!topics!forms_api_reference.html/8.
+   *
    * @param array $form
-   *   An associative array containing the structure of the form.
+   *   An associative array containing the initial structure of the plugin form.
    * @param \Drupal\Core\Form\FormStateInterface $form_state
-   *   The current state of the form.
+   *   The current state of the complete form.
    *
    * @return array
    *   The form structure.
@@ -44,9 +44,14 @@ public function buildConfigurationForm(array $form, FormStateInterface $form_sta
    * Form validation handler.
    *
    * @param array $form
-   *   An associative array containing the structure of the form.
+   *   An associative array containing the structure of the plugin form as built
+   *   by static::buildConfigurationForm().
    * @param \Drupal\Core\Form\FormStateInterface $form_state
-   *   The current state of the form.
+   *   The current state of the complete form. The values submitted for the
+   *   plugin form can be retrieved through
+   *   @code
+   *   \Drupal\Component\Utility\NestedArray::getValue($form_state->getValues(), $form['#parents']);
+   *   @endcode
    */
   public function validateConfigurationForm(array &$form, FormStateInterface $form_state);
 
@@ -54,9 +59,14 @@ public function validateConfigurationForm(array &$form, FormStateInterface $form
    * Form submission handler.
    *
    * @param array $form
-   *   An associative array containing the structure of the form.
+   *   An associative array containing the structure of the plugin form as built
+   *   by static::buildConfigurationForm().
    * @param \Drupal\Core\Form\FormStateInterface $form_state
-   *   The current state of the form.
+   *   The current state of the complete form. The values submitted for the
+   *   plugin form can be retrieved through
+   *   @code
+   *   \Drupal\Component\Utility\NestedArray::getValue($form_state->getValues(), $form['#parents']);
+   *   @endcode
    */
   public function submitConfigurationForm(array &$form, FormStateInterface $form_state);