diff -u b/core/lib/Drupal/Core/Render/Element/Actions.php b/core/lib/Drupal/Core/Render/Element/Actions.php
--- b/core/lib/Drupal/Core/Render/Element/Actions.php
+++ b/core/lib/Drupal/Core/Render/Element/Actions.php
@@ -13,8 +13,9 @@
 /**
  * Provides a wrapper element to group one or more buttons in a form.
  *
- * Use of the 'actions' element as an array key helps to ensure proper styling
- * in themes and to enable other modules to properly alter a form's actions.
+ * Use of a single Actions element with an array key of 'actions' to group the
+ * primary submit buttons on a form helps to ensure proper styling in themes,
+ * and enables other modules to properly alter a form's actions.
  *
  * Usage example:
  * @code
diff -u b/core/lib/Drupal/Core/Render/Element/Container.php b/core/lib/Drupal/Core/Render/Element/Container.php
--- b/core/lib/Drupal/Core/Render/Element/Container.php
+++ b/core/lib/Drupal/Core/Render/Element/Container.php
@@ -18,18 +18,27 @@
  *
  * Usage example:
  * @code
+ * $form['needs_accomodation'] = array(
+ *   '#type' => 'checkbox',
+ *   '#title' => 'Need Special Accomodations?',
+ * );
+ *
  * $form['accommodation'] = array(
  *   '#type' => 'container',
  *   '#attributes' => array(
  *     'class' => 'accomodation',
  *   ),
+ *   '#states' => array(
+ *     'invisible' => array(
+ *       'input[name="needs_accomodation"]' => array('checked' => FALSE),
+ *     ),
+ *   ),
  * );
  *
  * $form['accommodation']['diet'] = array(
  *   '#type' => 'textfield',
  *   '#title' => t('Dietary Restrictions'),
- *  );
- * ...
+ * );
  * @endcode
  *
  * @RenderElement("container")
diff -u b/core/lib/Drupal/Core/Render/Element/Details.php b/core/lib/Drupal/Core/Render/Element/Details.php
--- b/core/lib/Drupal/Core/Render/Element/Details.php
+++ b/core/lib/Drupal/Core/Render/Element/Details.php
@@ -13,25 +13,24 @@
  * Provides a render element for a details element, similar to a fieldset.
  *
  * Fieldsets can only be used in forms, while details elements can be used
- * outside of forms.
+ * outside of forms.  Users click on the the title to open or close the details
+ * element, showing or hiding the contained elements.
  *
  * Properties:
- * - #title: The title of the details container. Defaults to "Details"
- * - #open: Indicates whether the contained elements should be visible.
- *    Defaults to FALSE
+ * - #title: The title of the details container. Defaults to "Details".
+ * - #open: Indicates whether the container should be open by default.
+ *    Defaults to FALSE.
  *
  * Usage example:
  * @code
- * $form['clear_cache'] = array(
+ * $form['author'] = array(
  *   '#type' => 'details',
- *   '#title' => t('Clear cache'),
- *   '#open' => TRUE,
+ *   '#title' => 'Author',
  * );
  *
- * $form['clear_cache']['clear'] = array(
- *   '#type' => 'submit',
- *   '#value' => t('Clear all caches'),
- *   '#submit' => array('::submitCacheClear'),
+ * $form['author']['name'] = array(
+ *   '#type' => 'textfield',
+ *   '#title' => t('Name'),
  * );
  * @endcode
  *
diff -u b/core/lib/Drupal/Core/Render/Element/Fieldgroup.php b/core/lib/Drupal/Core/Render/Element/Fieldgroup.php
--- b/core/lib/Drupal/Core/Render/Element/Fieldgroup.php
+++ b/core/lib/Drupal/Core/Render/Element/Fieldgroup.php
@@ -11,24 +11,11 @@
  * Provides a render element for a group of form elements.
  *
  * In default rendering, the only difference between a 'fieldgroup' and a
- * 'fieldset' is the CSS class applied to the containing HTML element.
+ * 'fieldset' is the CSS class applied to the containing HTML element. Normally
+ * use a fieldset.
  *
- * @code
- * $form['name'] = array(
- *   '#type' => 'fieldgroup',
- *   '#title' => t('View basic information'),
- *   '#attributes' => array('class' => array('fieldset-no-legend')),
- * );
+ * @see \Drupal\Core\Render\Element\Fieldset for documentation and usage.
  *
- * $form['name']['label'] = array(
- *   '#type' => 'textfield',
- *   '#title' => $this->t('View name'),
- *   '#required' => TRUE,
- *   '#size' => 32,
- *   '#default_value' => '',
- *   '#maxlength' => 255,
- * );
- * ...
  * @endcode
  *
  * @see \Drupal\Core\Render\Element\Fieldset
diff -u b/core/lib/Drupal/Core/Render/Element/Fieldset.php b/core/lib/Drupal/Core/Render/Element/Fieldset.php
--- b/core/lib/Drupal/Core/Render/Element/Fieldset.php
+++ b/core/lib/Drupal/Core/Render/Element/Fieldset.php
@@ -12,25 +12,17 @@
 /**
  * Provides a render element for a group of form elements.
  *
- * In default rendering, the only difference between a 'fieldgroup' and a
- * 'fieldset' is the CSS class applied to the containing HTML element.
- *
+ * Usage example:
  * @code
- * $form['name'] = array(
+ * $form['author'] = array(
  *   '#type' => 'fieldset',
- *   '#title' => t('View basic information'),
- *   '#attributes' => array('class' => array('fieldset-no-legend')),
+ *   '#title' => 'Author',
  * );
  *
- * $form['name']['label'] = array(
+ * $form['author']['name'] = array(
  *   '#type' => 'textfield',
- *   '#title' => $this->t('View name'),
- *   '#required' => TRUE,
- *   '#size' => 32,
- *   '#default_value' => '',
- *   '#maxlength' => 255,
+ *   '#title' => t('Name'),
  * );
- * ...
  * @endcode
  *
  * @see \Drupal\Core\Render\Element\Fieldgroup
diff -u b/core/lib/Drupal/Core/Render/Element/Table.php b/core/lib/Drupal/Core/Render/Element/Table.php
--- b/core/lib/Drupal/Core/Render/Element/Table.php
+++ b/core/lib/Drupal/Core/Render/Element/Table.php
@@ -19,10 +19,12 @@
  *
  * Properties:
  * - #header: An array of table header labels.
- * - #rows: A two dimensional array containing the rows and columns of the table
- *   to be displayed.  Alternatively specify the data for the table as child
- *   elements of the table element.
- * - #empty: Text to display when no rows are present.
+ * - #rows: An array of the rows to be displayed. Each row is either an array
+ *   of cell contents or an array of properties as described in table.html.twig
+ * - #empty: Text to display when no rows are present. Alternatively specify
+ *   the data for the table as child elements of the table element. Table
+ *   elements would contain rows elements that would in turn contain
+ *   column elements.
  * - #responsive: Indicates whether to add the drupal.responsive_table library
  *   providing responsive tables.  Defaults to TRUE.
  * - #sticky: Indicates whether to add the drupal.tableheader library that makes
diff -u b/core/lib/Drupal/Core/Render/Element/VerticalTabs.php b/core/lib/Drupal/Core/Render/Element/VerticalTabs.php
--- b/core/lib/Drupal/Core/Render/Element/VerticalTabs.php
+++ b/core/lib/Drupal/Core/Render/Element/VerticalTabs.php
@@ -16,8 +16,9 @@
  * Formats all child and non-child details elements whose #group is assigned
  * this element's name as vertical tabs.
  *
- * Poperties:
- * - #default_tab: The id of the details element to be used as the default tab
+ * Properties:
+ * - #default_tab: The html ID of the rendered details element to be used as
+ *   the default tab. View the source of the rendered page to determine the ID.
  *
  * Usage example:
  * @code