diff --git a/core/lib/Drupal/Core/Form/FormHelper.php b/core/lib/Drupal/Core/Form/FormHelper.php
index 4f9ef027b9..ffced04686 100644
--- a/core/lib/Drupal/Core/Form/FormHelper.php
+++ b/core/lib/Drupal/Core/Form/FormHelper.php
@@ -13,10 +13,14 @@
 class FormHelper {
 
   /**
-   * Rewrite #states selectors.
+   * Rewrites #states selectors in a render element.
+   *
+   * When a structure of elements is being altered, their HTML selectors may
+   * change. In such cases calling this method will check if there are any
+   * states in element and its children, and rewrite selectors in those states.
    *
    * @param array $elements
-   *   A renderable array element having a #states property.
+   *   A render array element having a #states property.
    * @param string $search
    *   A partial or entire jQuery selector string to replace in #states.
    * @param string $replace
@@ -36,7 +40,10 @@ public static function rewriteStatesSelector(array &$elements, $search, $replace
   }
 
   /**
-   * Helper function for self::rewriteStatesSelector().
+   * Helps recursively rewrite #states selectors.
+   *
+   * Not to be confused with self::processStates(), which just prepares states
+   * for rendering.
    *
    * @param array $conditions
    *   States conditions array.
@@ -44,6 +51,8 @@ public static function rewriteStatesSelector(array &$elements, $search, $replace
    *   A partial or entire jQuery selector string to replace in #states.
    * @param string $replace
    *   The string to replace all instances of $search with.
+   *
+   * @see self::rewriteStatesSelector()
    */
   protected static function processStatesArray(array &$conditions, $search, $replace) {
     // Retrieve the keys to make it easy to rename a key without changing the
@@ -71,10 +80,11 @@ protected static function processStatesArray(array &$conditions, $search, $repla
   /**
    * Adds JavaScript to change the state of an element based on another element.
    *
-   * A "state" means a certain property on a DOM element, such as "visible" or
-   * "checked". A state can be applied to an element, depending on the state of
-   * another element on the page. In general, states depend on HTML attributes
-   * and DOM element properties, which change due to user interaction.
+   * A "state" means a certain property of a DOM element, such as "visible" or
+   * "checked", which depends on a state or value of another element on the
+   * page. In general, states are HTML attributes and DOM element properties,
+   * which are applied initially, when page is loaded, depending on elements'
+   * default values, and then may change due to user interaction.
    *
    * Since states are driven by JavaScript only, it is important to understand
    * that all states are applied on presentation only, none of the states force