diff -u b/core/modules/block/block.api.php b/core/modules/block/block.api.php
--- b/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -20,8 +20,8 @@
  * If the module wishes to act on the rendered HTML of the block rather than
  * the structured content array, it may use this hook to add a #post_render
  * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
- * block.html.twig. See drupal_render() documentation or the @link themeable
- * Default theme implementations topic @endlink for details.
+ * block.html.twig. See drupal_render() documentation or the
+ * @link themeable Default theme implementations topic @endlink for details.
  *
  * In addition to hook_block_view_alter(), which is called for all blocks, there
  * is hook_block_view_BASE_BLOCK_ID_alter(), which can be used to target a
diff -u b/core/modules/node/node.api.php b/core/modules/node/node.api.php
--- b/core/modules/node/node.api.php
+++ b/core/modules/node/node.api.php
@@ -817,7 +817,8 @@
  * If the module wishes to act on the rendered HTML of the node rather than the
  * structured content array, it may use this hook to add a #post_render
  * callback.  Alternatively, it could also implement hook_preprocess_HOOK() for
- * node.html.twig. See drupal_render() documentation for details.
+ * node.html.twig. See drupal_render() documentation or the
+ * @link themeable Default theme implementations topic @endlink for details.
  *
  * @param &$build
  *   A renderable array representing the node content.
diff -u b/core/modules/system/system.api.php b/core/modules/system/system.api.php
--- b/core/modules/system/system.api.php
+++ b/core/modules/system/system.api.php
@@ -976,6 +976,7 @@
 
 /**
  * Register a module or theme's theme implementations.
+ *
  * The implementations declared by this hook specify how a particular render
  * array is to be rendered as HTML.
  *
@@ -1009,8 +1010,16 @@
  *   For render elements, the key is the machine name of the render element.
  *   The array values are themselves arrays containing information about the
  *   theme hook and its implementation. Each information array must contain
- *   a 'render element' element.
+ *   either a 'variables' element (for using a #theme element) or a
+ *   'render element' element (for render elements), but not both.
  *   The following elements may be part of each information array:
+ *   - variables: Only used for #theme in render array: an array of variables,
+ *     where the array keys are the names of the variables, and the array
+ *     values are the default values if they are not passed to #theme in render
+ *     array. Template implementations receive each array key as a variable in
+ *     the template file (so they must be legal PHP/Twig variable names).
+ *     Function implementations are passed the variables in a single $variables
+ *     function argument.
  *   - render element: Used for render element items only: the name of the
  *     renderable element or element tree to pass to the theme function. This
  *     name is used as the name of the variable that holds the renderable
@@ -1028,6 +1037,27 @@
  *     this file; that extension will be added automatically by the default
  *     rendering engine (which is Twig). If 'path' above is specified, the
  *     template should also be in this path.
+ *   - base hook: Used for #theme suggestions only: the base theme hook name.
+ *     Instead of this suggestion's implementation being used directly, the base
+ *     hook will be invoked with this implementation as its first suggestion.
+ *     The base hook's files will be included and the base hook's preprocess
+ *     functions will be called in place of any suggestion's preprocess
+ *     functions. If an implementation of hook_theme_suggestions_HOOK() (where
+ *     HOOK is the base hook) changes the suggestion order, a different
+ *     suggestion may be used in place of this suggestion. If after
+ *     hook_theme_suggestions_HOOK() this suggestion remains the first
+ *     suggestion, then this suggestion's function or template will be used to
+ *     generate the output for #theme in render array.
+ *   - pattern: A regular expression pattern to be used to allow this theme
+ *     implementation to have a dynamic name. The convention is to use __ to
+ *     differentiate the dynamic portion of the theme. For example, to allow
+ *     forums to be themed individually, the pattern might be: 'forum__'. Then,
+ *     when the forum is themed, call:
+ *     @code
+ *     $render_array = array(
+ *       #theme => array('forum__' . $tid, 'forum'), $forum,
+ *     )
+ *     @endcode
  *   - preprocess functions: A list of functions used to preprocess this data.
  *     Ordinarily this won't be used; it's automatically filled in. By default,
  *     for a module this will be filled in as template_preprocess_HOOK. For
@@ -1041,6 +1071,8 @@
  *     set, this can be set to true. Please keep in mind that when this is used
  *     by a theme, that theme becomes responsible for making sure necessary
  *     variables are set.
+ *   - type: (automatically derived) Where the theme hook is defined:
+ *     'module', 'theme_engine', or 'theme'.
  *   - theme path: (automatically derived) The directory path of the theme or
  *     module, so that it doesn't need to be looked up.
  *
diff -u b/core/modules/user/user.api.php b/core/modules/user/user.api.php
--- b/core/modules/user/user.api.php
+++ b/core/modules/user/user.api.php
@@ -345,8 +345,8 @@
  * If the module wishes to act on the rendered HTML of the user rather than the
  * structured content array, it may use this hook to add a #post_render
  * callback. Alternatively, it could also implement hook_preprocess_HOOK() for
- * user.html.twig. See drupal_render() documentation or @link themeable
- * Default theme implementations topic @endlink for details.
+ * user.html.twig. See drupal_render() documentation or
+ * @link themeable Default theme implementations topic @endlink for details.
  *
  * @param array &$build
  *   A renderable array representing the user.