diff --git a/core/lib/Drupal/Core/Render/Annotation/FormElement.php b/core/lib/Drupal/Core/Render/Annotation/FormElement.php
index b7288a0..4d4b593 100644
--- a/core/lib/Drupal/Core/Render/Annotation/FormElement.php
+++ b/core/lib/Drupal/Core/Render/Annotation/FormElement.php
@@ -10,19 +10,20 @@
 /**
  * Defines a form element plugin annotation object.
  *
- * Form elements are also valid render elements, but they specifically represent
- * an HTML element that takes input as part of a form. It will be discovered via
- * the same mechanism as regular render element plugins.
+ * See \Drupal\Core\Render\Element\FormElementInterface for more information
+ * about form element plugins.
  *
  * Plugin Namespace: Element
  *
  * For a working example, see \Drupal\Core\Render\Element\Textfield.
  *
  * @see \Drupal\Core\Render\ElementInfoManager
- * @see \Drupal\Core\Render\ElementInterface
- * @see \Drupal\Core\Render\FormElement
+ * @see \Drupal\Core\Render\Element\FormElementInterface
+ * @see \Drupal\Core\Render\Element\FormElement
+ * @see \Drupal\Core\Render\Annotation\RenderElement
+ * @see plugin_api
  *
- * @ingroup plugin_api
+ * @ingroup theme_render
  *
  * @Annotation
  */
diff --git a/core/lib/Drupal/Core/Render/Annotation/RenderElement.php b/core/lib/Drupal/Core/Render/Annotation/RenderElement.php
index cb03875..fc36b32 100644
--- a/core/lib/Drupal/Core/Render/Annotation/RenderElement.php
+++ b/core/lib/Drupal/Core/Render/Annotation/RenderElement.php
@@ -12,24 +12,20 @@
 /**
  * Defines a render element plugin annotation object.
  *
- * Render element plugins allow modules to declare their own Render API element
- * types and specify their default values.
- *
- * This annotation allows modules to declare their own render element types and
- * to specify their default values. The values returned by this plugin will be
- * merged with the elements returned by render arrays and so can return defaults
- * for any Render APIs keys in addition to those explicitly documented by
- * \Drupal\Core\Render\ElementInfoManagerInterface::getInfo().
+ * See \Drupal\Core\Render\Element\ElementInterface for more information
+ * about render element plugins.
  *
  * Plugin Namespace: Element
  *
  * For a working example, see \Drupal\Core\Render\Element\Link.
  *
  * @see \Drupal\Core\Render\ElementInfoManager
- * @see \Drupal\Core\Render\ElementInterface
- * @see \Drupal\Core\Render\RenderElement
+ * @see \Drupal\Core\Render\Element\ElementInterface
+ * @see \Drupal\Core\Render\Element\RenderElement
+ * @see \Drupal\Core\Render\Annotation\FormElement
+ * @see plugin_api
  *
- * @ingroup plugin_api
+ * @ingroup theme_render
  *
  * @Annotation
  */
diff --git a/core/lib/Drupal/Core/Render/Element.php b/core/lib/Drupal/Core/Render/Element.php
index 501f2de..eed5c30 100644
--- a/core/lib/Drupal/Core/Render/Element.php
+++ b/core/lib/Drupal/Core/Render/Element.php
@@ -10,7 +10,11 @@
 use Drupal\Component\Utility\String;
 
 /**
- * Deals with drupal render elements.
+ * Provides helper methods for Drupal render elements.
+ *
+ * @see \Drupal\Core\Render\Element\ElementInterface
+ *
+ * @ingroup theme_render
  */
 class Element {
 
@@ -47,7 +51,7 @@ public static function properties(array $element) {
    *   The key to check.
    *
    * @return bool
-   *    TRUE if the element is a child, FALSE otherwise.
+   *   TRUE if the element is a child, FALSE otherwise.
    */
   public static function child($key) {
     return !isset($key[0]) || $key[0] != '#';
@@ -143,11 +147,11 @@ public static function getVisibleChildren(array $elements) {
    * @param array $element
    *   The renderable element to process. Passed by reference.
    * @param array $map
-   *   An associative array whose keys are element property names and whose values
-   *   are the HTML attribute names to set for corresponding the property; e.g.,
-   *   array('#propertyname' => 'attributename'). If both names are identical
-   *   except for the leading '#', then an attribute name value is sufficient and
-   *   no property name needs to be specified.
+   *   An associative array whose keys are element property names and whose
+   *   values are the HTML attribute names to set on the corresponding
+   *   property; e.g., array('#propertyname' => 'attributename'). If both names
+   *   are identical except for the leading '#', then an attribute name value is
+   *   sufficient and no property name needs to be specified.
    */
   public static function setAttributes(array &$element, array $map) {
     foreach ($map as $property => $attribute) {
diff --git a/core/lib/Drupal/Core/Render/Element/ElementInterface.php b/core/lib/Drupal/Core/Render/Element/ElementInterface.php
index 020e18a..a1035f7 100644
--- a/core/lib/Drupal/Core/Render/Element/ElementInterface.php
+++ b/core/lib/Drupal/Core/Render/Element/ElementInterface.php
@@ -12,11 +12,22 @@
 /**
  * Provides an interface for element plugins.
  *
+ * Render element plugins allow modules to declare their own Render API element
+ * types and specify the default values for the properties. The values returned
+ * by the getInfo() method of the element plugin will be merged with the
+ * properties specified in render arrays. Thus, you can specify defaults for any
+ * Render API keys, in addition to those explicitly documented by
+ * \Drupal\Core\Render\ElementInfoManagerInterface::getInfo().
+ *
+ * Some render elements are specifically form input elements; see
+ * \Drupal\Core\Render\Element\FormElementInterface for more information.
+ *
  * @see \Drupal\Core\Render\ElementInfoManager
  * @see \Drupal\Core\Render\Annotation\RenderElement
- * @see \Drupal\Core\Render\Annotation\FormElement
- * @see \Drupal\Core\Render\RenderElement
- * @see \Drupal\Core\Render\FormElement
+ * @see \Drupal\Core\Render\Element\RenderElement
+ * @see plugin_api
+ *
+ * @ingroup theme_render
  */
 interface ElementInterface extends PluginInspectionInterface {
 
@@ -24,7 +35,10 @@
    * Returns the element properties for this element.
    *
    * @return array
-   *   An array of element properties.
+   *   An array of element properties. See
+   *   \Drupal\Core\Render\ElementInfoManagerInterface::getInfo() for
+   *   documentation of the standard properties of all elements, and the
+   *   return value format.
    */
   public function getInfo();
 
diff --git a/core/lib/Drupal/Core/Render/Element/FormElement.php b/core/lib/Drupal/Core/Render/Element/FormElement.php
index 95589d1..d66cc89 100644
--- a/core/lib/Drupal/Core/Render/Element/FormElement.php
+++ b/core/lib/Drupal/Core/Render/Element/FormElement.php
@@ -13,10 +13,11 @@
  * Provides a base class for form render plugins.
  *
  * @see \Drupal\Core\Render\Annotation\FormElement
- * @see \Drupal\Core\Render\ElementInterface
+ * @see \Drupal\Core\Render\Element\FormElementInterface
  * @see \Drupal\Core\Render\ElementInfoManager
+ * @see plugin_api
  *
- * @ingroup plugin_api
+ * @ingroup theme_render
  */
 abstract class FormElement extends RenderElement implements FormElementInterface {
 
@@ -109,25 +110,29 @@ public static function processPattern(&$element, FormStateInterface $form_state,
   }
 
   /**
-   * Adds autocomplete functionality to elements with a valid
-   * #autocomplete_route_name.
+   * Adds autocomplete functionality to elements.
    *
-   * Suppose your autocomplete route name is 'mymodule.autocomplete' and its path
-   * is: '/mymodule/autocomplete/{a}/{b}'
-   * In your form you have:
+   * This sets up autocomplete functionality for elements with an
+   * #autocomplete_route_name property, using the #autocomplete_route_parameters
+   * property if present.
+   *
+   * For example, suppose your autocomplete route name is
+   * 'mymodule.autocomplete' and its path is
+   * '/mymodule/autocomplete/{a}/{b}'. In a form array, you would create a text
+   * field with properties:
    * @code
    * '#autocomplete_route_name' => 'mymodule.autocomplete',
    * '#autocomplete_route_parameters' => array('a' => $some_key, 'b' => $some_id),
    * @endcode
-   * The user types in "keywords" so the full path called is:
+   * If the user types "keywords" in that field, the full path called would be:
    * 'mymodule_autocomplete/$some_key/$some_id?q=keywords'
    *
    * @param array $element
    *   The form element to process. Properties used:
    *   - #autocomplete_route_name: A route to be used as callback URL by the
    *     autocomplete JavaScript library.
-   *   - #autocomplete_route_parameters: The parameters to be used in conjunction
-   *     with the route name.
+   *   - #autocomplete_route_parameters: The parameters to be used in
+   *     conjunction with the route name.
    * @param \Drupal\Core\Form\FormStateInterface $form_state
    *   The current state of the form.
    * @param array $complete_form
diff --git a/core/lib/Drupal/Core/Render/Element/FormElementInterface.php b/core/lib/Drupal/Core/Render/Element/FormElementInterface.php
index 861ad39..2bbbde8 100644
--- a/core/lib/Drupal/Core/Render/Element/FormElementInterface.php
+++ b/core/lib/Drupal/Core/Render/Element/FormElementInterface.php
@@ -11,6 +11,19 @@
 
 /**
  * Provides an interface for form element plugins.
+ *
+ * Form element plugins are a subset of render elements, specifically
+ * representing HTML elements that take input as part of a form. Form element
+ * plugins are discovered via the same mechanism as regular render element
+ * plugins. See \Drupal\Core\Render\Element\ElementInterface for general
+ * information about render element plugins.
+ *
+ * @see \Drupal\Core\Render\ElementInfoManager
+ * @see \Drupal\Core\Render\Element\FormElement
+ * @see \Drupal\Core\Render\Annotation\FormElement
+ * @see plugin_api
+ *
+ * @ingroup theme_render
  */
 interface FormElementInterface extends ElementInterface {
 
diff --git a/core/lib/Drupal/Core/Render/Element/Link.php b/core/lib/Drupal/Core/Render/Element/Link.php
index 379b0a7..2a06eb6 100644
--- a/core/lib/Drupal/Core/Render/Element/Link.php
+++ b/core/lib/Drupal/Core/Render/Element/Link.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\Render\Element;
 
 /**
- * Provides a link element.
+ * Provides a link render element.
  *
  * @RenderElement("link")
  */
@@ -35,8 +35,9 @@ public function getInfo() {
    *   A structured array whose keys form the arguments to l():
    *   - #title: The link text to pass as argument to l().
    *   - One of the following
-   *     - #route_name and (optionally) and a #route_parameters array; The route
-   *       name and route parameters which will be passed into the link generator.
+   *     - #route_name and (optionally) a #route_parameters array; The route
+   *       name and route parameters which will be passed into the link
+   *       generator.
    *     - #href: The system path or URL to pass as argument to l().
    *   - #options: (optional) An array of options to pass to l() or the link
    *     generator.
diff --git a/core/lib/Drupal/Core/Render/Element/MachineName.php b/core/lib/Drupal/Core/Render/Element/MachineName.php
index 42f00cb..6301f35 100644
--- a/core/lib/Drupal/Core/Render/Element/MachineName.php
+++ b/core/lib/Drupal/Core/Render/Element/MachineName.php
@@ -12,7 +12,7 @@
 use Drupal\Core\Form\FormStateInterface;
 
 /**
- * Format a single-line text field to store a unique machine-readable name.
+ * Provides a machine name render element.
  *
  * Provides a form element to enter a machine name, which is validated to ensure
  * that the name is unique and does not contain disallowed characters. All
@@ -67,27 +67,29 @@ public static function valueCallback(&$element, $input, FormStateInterface $form
    *     - exists: A callable to invoke for checking whether a submitted machine
    *       name value already exists. The submitted value is passed as an
    *       argument. In most cases, an existing API or menu argument loader
-   *       function can be re-used. The callback is only invoked, if the submitted
-   *       value differs from the element's #default_value.
+   *       function can be re-used. The callback is only invoked if the
+   *       submitted value differs from the element's #default_value.
    *     - source: (optional) The #array_parents of the form element containing
-   *       the human-readable name (i.e., as contained in the $form structure) to
-   *       use as source for the machine name. Defaults to array('label').
-   *     - label: (optional) A text to display as label for the machine name value
-   *       after the human-readable name form element. Defaults to "Machine name".
+   *       the human-readable name (i.e., as contained in the $form structure)
+   *       to use as source for the machine name. Defaults to array('label').
+   *     - label: (optional) Text to display as label for the machine name value
+   *       after the human-readable name form element. Defaults to "Machine
+   *       name".
    *     - replace_pattern: (optional) A regular expression (without delimiters)
    *       matching disallowed characters in the machine name. Defaults to
    *       '[^a-z0-9_]+'.
-   *     - replace: (optional) A character to replace disallowed characters in the
-   *       machine name via JavaScript. Defaults to '_' (underscore). When using a
-   *       different character, 'replace_pattern' needs to be set accordingly.
+   *     - replace: (optional) A character to replace disallowed characters in
+   *       the machine name via JavaScript. Defaults to '_' (underscore). When
+   *       using a different character, 'replace_pattern' needs to be set
+   *       accordingly.
    *     - error: (optional) A custom form error message string to show, if the
    *       machine name contains disallowed characters.
-   *     - standalone: (optional) Whether the live preview should stay in its own
-   *       form element rather than in the suffix of the source element. Defaults
-   *       to FALSE.
-   *   - #maxlength: (optional) Should be set to the maximum allowed length of the
-   *     machine name. Defaults to 64.
-   *   - #disabled: (optional) Should be set to TRUE in case an existing machine
+   *     - standalone: (optional) Whether the live preview should stay in its
+   *       own form element rather than in the suffix of the source
+   *       element. Defaults to FALSE.
+   *   - #maxlength: (optional) Maximum allowed length of the machine name.
+   *     Defaults to 64.
+   *   - #disabled: (optional) Should be set to TRUE if an existing machine
    *     name must not be changed after initial creation.
    * @param \Drupal\Core\Form\FormStateInterface $form_state
    *   The current state of the form.
@@ -181,12 +183,12 @@ public static function processMachineName(&$element, FormStateInterface $form_st
    *
    * Note that #maxlength is validated by _form_validate() already.
    *
-   * This checks that the submitted value
-   * - does not contain the replacement character only
-   * - does not contain disallowed characters
-   * - is unique; i.e., does not already exist
-   * - does not exceed the maximum length (via #maxlength)
-   * - cannot be changed after creation (via #disabled)
+   * This checks that the submitted value:
+   * - Does not contain the replacement character only.
+   * - Does not contain disallowed characters.
+   * - Is unique; i.e., does not already exist.
+   * - Does not exceed the maximum length (via #maxlength).
+   * - Cannot be changed after creation (via #disabled).
    */
   public static function validateMachineName(&$element, FormStateInterface $form_state, &$complete_form) {
     // Verify that the machine name not only consists of replacement tokens.
diff --git a/core/lib/Drupal/Core/Render/Element/RenderElement.php b/core/lib/Drupal/Core/Render/Element/RenderElement.php
index 19cb772..cf4d454 100644
--- a/core/lib/Drupal/Core/Render/Element/RenderElement.php
+++ b/core/lib/Drupal/Core/Render/Element/RenderElement.php
@@ -16,8 +16,9 @@
  * @see \Drupal\Core\Render\Annotation\RenderElement
  * @see \Drupal\Core\Render\ElementInterface
  * @see \Drupal\Core\Render\ElementInfoManager
+ * @see plugin_api
  *
- * @ingroup plugin_api
+ * @ingroup theme_render
  */
 abstract class RenderElement extends PluginBase implements ElementInterface {
 
diff --git a/core/lib/Drupal/Core/Render/Element/Textfield.php b/core/lib/Drupal/Core/Render/Element/Textfield.php
index db2b816..d687a2c 100644
--- a/core/lib/Drupal/Core/Render/Element/Textfield.php
+++ b/core/lib/Drupal/Core/Render/Element/Textfield.php
@@ -11,7 +11,7 @@
 use Drupal\Core\Render\Element;
 
 /**
- * Formats a single-line text field.
+ * Provides a one-line text field form element.
  *
  * @FormElement("textfield")
  */
diff --git a/core/lib/Drupal/Core/Render/ElementInfoManager.php b/core/lib/Drupal/Core/Render/ElementInfoManager.php
index fb02e83..1dd2be4 100644
--- a/core/lib/Drupal/Core/Render/ElementInfoManager.php
+++ b/core/lib/Drupal/Core/Render/ElementInfoManager.php
@@ -15,13 +15,13 @@
 /**
  * Provides a plugin manager for element plugins.
  *
- * @see \Drupal\Core\Render\ElementInterface
  * @see \Drupal\Core\Render\Annotation\RenderElement
  * @see \Drupal\Core\Render\Annotation\FormElement
- * @see \Drupal\Core\Render\RenderElement
- * @see \Drupal\Core\Render\FormElement
- *
- * @ingroup plugin_api
+ * @see \Drupal\Core\Render\Element\RenderElement
+ * @see \Drupal\Core\Render\Element\FormElement
+ * @see \Drupal\Core\Render\Element\ElementInterface
+ * @see \Drupal\Core\Render\Element\FormElementInterface
+ * @see plugin_api
  */
 class ElementInfoManager extends DefaultPluginManager implements ElementInfoManagerInterface {
 
diff --git a/core/lib/Drupal/Core/Render/ElementInfoManagerInterface.php b/core/lib/Drupal/Core/Render/ElementInfoManagerInterface.php
index 423965f..d32acd6 100644
--- a/core/lib/Drupal/Core/Render/ElementInfoManagerInterface.php
+++ b/core/lib/Drupal/Core/Render/ElementInfoManagerInterface.php
@@ -8,7 +8,7 @@
 namespace Drupal\Core\Render;
 
 /**
- * Defines available render array element types.
+ * Collects available render array element types.
  */
 interface ElementInfoManagerInterface {
 
@@ -16,35 +16,39 @@
    * Retrieves the default properties for the defined element type.
    *
    * Each of the form element types defined by this hook is assumed to have
-   * a matching theme function, e.g. theme_elementtype(), which should be
-   * registered with hook_theme() as normal.
+   * a matching theme hook, which should be registered with hook_theme() as
+   * normal.
    *
    * For more information about custom element types see the explanation at
    * http://drupal.org/node/169815.
    *
    * @param string $type
-   *   An element type as defined by hook_element_info().
+   *   An element type as defined by hook_element_info() or the machine name
+   *   of an element type plugin.
    *
    * @return array
-   *  An associative array describing the element types being defined. The array
-   *  contains a sub-array for each element type, with the machine-readable type
-   *  name as the key. Each sub-array has a number of possible attributes:
-   *  - "#input": boolean indicating whether or not this element carries a value
-   *    (even if it's hidden).
-   *  - "#process": array of callback functions taking $element, $form_state,
-   *    and $complete_form.
-   *  - "#after_build": array of callables taking $element and $form_state.
-   *  - "#validate": array of callback functions taking $form and $form_state.
-   *  - "#element_validate": array of callback functions taking $element and
-   *    $form_state.
-   *  - "#pre_render": array of callables taking $element.
-   *  - "#post_render": array of callables taking $children and $element.
-   *  - "#submit": array of callback functions taking $form and $form_state.
-   *  - "#title_display": optional string indicating if and how #title should be
-   *    displayed, see the form-element template and theme_form_element_label().
+   *   An associative array describing the element types being defined. The
+   *   array contains a sub-array for each element type, with the
+   *   machine-readable type name as the key. Each sub-array has a number of
+   *   possible attributes:
+   *   - #input: boolean indicating whether or not this element carries a value
+   *     (even if it's hidden).
+   *   - #process: array of callback functions taking $element, $form_state,
+   *     and $complete_form.
+   *   - #after_build: array of callables taking $element and $form_state.
+   *   - #validate: array of callback functions taking $form and $form_state.
+   *   - #element_validate: array of callback functions taking $element and
+   *     $form_state.
+   *   - #pre_render: array of callables taking $element.
+   *   - #post_render: array of callables taking $children and $element.
+   *   - #submit: array of callback functions taking $form and $form_state.
+   *   - #title_display: optional string indicating if and how #title should be
+   *     displayed (see form-element.html.twig).
    *
    * @see hook_element_info()
    * @see hook_element_info_alter()
+   * @see \Drupal\Core\Render\Element\ElementInterface
+   * @see \Drupal\Core\Render\Element\ElementInterface::getInfo()
    */
   public function getInfo($type);
 
diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index 85eb728..fabde88 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -163,11 +163,21 @@
  * requests and the CSS files used to style that markup. In order to ensure that
  * a theme can completely customize the markup, module developers should avoid
  * directly writing HTML markup for pages, blocks, and other user-visible output
- * in their modules, and instead return structured "render arrays" (described
- * below). Doing this also increases usability, by ensuring that the markup used
- * for similar functionality on different areas of the site is the same, which
- * gives users fewer user interface patterns to learn.
+ * in their modules, and instead return structured "render arrays" (see @ref
+ * arrays below). Doing this also increases usability, by ensuring that the
+ * markup used for similar functionality on different areas of the site is the
+ * same, which gives users fewer user interface patterns to learn.
  *
+ * For further information on the Theme and Render APIs, see:
+ * - https://drupal.org/documentation/theme
+ * - https://drupal.org/node/722174
+ * - https://drupal.org/node/933976
+ * - https://drupal.org/node/930760
+ *
+ * @todo Check these links. Some are for Drupal 7, and might need updates for
+ *   Drupal 8.
+ *
+ * @section arrays Render arrays
  * The core structure of the Render API is the render array, which is a
  * hierarchical associative array containing data to be rendered and properties
  * describing how the data should be rendered. A render array that is returned
@@ -194,11 +204,8 @@
  * - #type: Specifies that the array contains data and options for a particular
  *   type of "render element" (examples: 'form', for an HTML form; 'textfield',
  *   'submit', and other HTML form element types; 'table', for a table with
- *   rows, columns, and headers). Modules define render elements by implementing
- *   hook_element_info(), which specifies the properties that are used in render
- *   arrays to provide the data and options, and default values for these
- *   properties. Look through implementations of hook_element_info() to discover
- *   what render elements are available.
+ *   rows, columns, and headers). See @ref elements below for more on render
+ *   element types.
  * - #theme: Specifies that the array contains data to be themed by a particular
  *   theme hook. Modules define theme hooks by implementing hook_theme(), which
  *   specifies the input "variables" used to provide data and options; if a
@@ -214,15 +221,29 @@
  *   normally preferable to use #theme or #type instead, so that the theme can
  *   customize the markup.
  *
- * For further information on the Theme and Render APIs, see:
- * - https://drupal.org/documentation/theme
- * - https://drupal.org/developing/modules/8
- * - https://drupal.org/node/722174
- * - https://drupal.org/node/933976
- * - https://drupal.org/node/930760
+ * @section elements Render elements
+ * Render elements are defined by Drupal core and modules. The primary way to
+ * define a render element is to create a render element plugin. There are
+ * two types of render element plugins:
+ * - Generic elements: Generic render element plugins implement
+ *   \Drupal\Core\Render\Element\ElementInterface, are annotated with
+ *   \Drupal\Core\Render\Annotation\RenderElement annotation, go in plugin
+ *   namespace Element, and generally extend the
+ *   \Drupal\Core\Render\Element\RenderElement base class.
+ * - Form input elements: Render elements representing form input elements
+ *   implement \Drupal\Core\Render\Element\FormElementInterface, are annotated
+ *   with \Drupal\Core\Render\Annotation\FormElement annotation, go in plugin
+ *   namespace Element, and generally extend the
+ *   \Drupal\Core\Render\Element\FormElement base class.
+ * See the @link plugin_api Plugin API topic @endlink for general information
+ * on plugins, and look for classes with the RenderElement or FormElement
+ * annotation to discover what render elements are available.
+ *
+ * Modules can also currently define render elements by implementing
+ * hook_element_info(), although defining a plugin is preferred.
+ * properties. Look through implementations of hook_element_info() to discover
+ * elements defined this way.
  *
- * @todo Check these links. Some are for Drupal 7, and might need updates for
- *   Drupal 8.
  * @see themeable
  *
  * @}