Issue #2486993 by metzlerd, jhodgdon: Document Hidden Form Elements

core/lib/Drupal/Core/Render/Element/Hidden.php

@@ -12,6 +12,19 @@
 /**
  * Provides a form element for an HTML 'hidden' input element.
  *
+ * Specify either #default_value or #value but not both.
+ *
+ * Properties:
+ * - #default_value: The initial value of the form element. JavaScript may
+ *   alter the value prior to submission.
+ * - #value: The value of the form element. The Form API ensures that this
+ *   value remains unchanged by the browser.
+ *
+ * Usage example:
+ * @code
+ * $form['entity_id'] = array('#type' => 'hidden', '#value' => $entity_id);
+ * @endcode
+ *
  * @see \Drupal\Core\Render\Element\Value
  *
  * @FormElement("hidden")

core/lib/Drupal/Core/Render/Element/Value.php

@@ -10,9 +10,17 @@
 /**
  * Provides a form element for storage of internal information.
  *
- * Unlike \Drupal\Core\Render\Element\Hidden, this information is not
- * sent to the browser in a hidden form field, but is just stored in the form
- * array for use in validation and submit processing.
+ * Unlike \Drupal\Core\Render\Element\Hidden, this information is not sent to
+ * the browser in a hidden form field, but only stored in the form array for use
+ * in validation and submit processing.
+ *
+ * Properties:
+ * - #value: The value of the form element that cannot be edited by the user.
+ *
+ * Usage Example:
+ * @code
+ * $form['entity_id'] = array('#type' => 'value', '#value' => $entity_id);
+ * @endcode
  *
  * @FormElement("value")
  */