diff --git a/core/includes/theme.inc b/core/includes/theme.inc
index b7dce9e..6a68f5b 100644
--- a/core/includes/theme.inc
+++ b/core/includes/theme.inc
@@ -340,7 +340,7 @@ function list_themes($refresh = FALSE) {
 }
 
 /**
- * Generates themed output.
+ * Generates themed output (internal use only).
  *
  * _theme() is an internal function. Do not call this function directly as it
  * will prevent the following items from working correctly:
diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index 6b76846..7f7a73f 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -38,19 +38,19 @@
  * @endcode
  *
  * @section sec_theme_hooks Theme Hooks
- * Most commonly, the first argument to this function is the name of the theme
- * hook. For instance, to theme a taxonomy term, the theme hook name is
- * 'taxonomy_term'. Modules register theme hooks within a hook_theme()
- * implementation and provide a default implementation via a function named
- * theme_HOOK() (e.g., theme_taxonomy_term()) or via a template file named
- * according to the value of the 'template' key registered with the theme hook
- * (see hook_theme() for details). Default templates are implemented with the
- * Twig rendering engine and are named the same as the theme hook, with
- * underscores changed to hyphens, so for the 'taxonomy_term' theme hook, the
- * default template is 'taxonomy-term.html.twig'.
+ * Modules register theme hooks within a hook_theme()implementation and provide
+ * a default implementation via a function named theme_HOOK(). For instance, to
+ * theme a taxonomy term, the theme hook name is 'taxonomy_term'. If theming is
+ * handled via a function then the corresponding function name is
+ * theme_taxonomy_term(). If theming is handled via a template then the file
+ * should be named according to the value of the 'template' key registered with
+ * the theme hook (see hook_theme() for details). Default templates are
+ * implemented with the Twig rendering engine and are named the same as the
+ * theme hook, with underscores changed to hyphens, so for the 'taxonomy_term'
+ * theme hook, the default template is 'taxonomy-term.html.twig'.
  *
  * @subsection sub_overriding_theme_hooks Overriding Theme Hooks
- * Themes may also register new theme hooks within a hook_theme()
+ * Themes may register new theme hooks within a hook_theme()
  * implementation, but it is more common for themes to override default
  * implementations provided by modules than to register entirely new theme
  * hooks. Themes can override a default implementation by implementing a
@@ -58,9 +58,9 @@
  * default implementation of the 'menu_tree' theme hook by implementing a
  * bartik_menu_tree() function), or by adding a template file within its folder
  * structure that follows the template naming structure used by the theme's
- * rendering engine (for example, since the Bartik theme uses the Twig rendering
+ * rendering engine. For example, since the Bartik theme uses the Twig rendering
  * engine, it overrides the default implementation of the 'page' theme hook by
- * containing a 'page.html.twig' file within its folder structure).
+ * containing a 'page.html.twig' file within its folder structure.
  *
  * @subsection sub_preprocess_templates Preprocessing for Template Files
  * If the implementation is a template file, several functions are called before
@@ -88,11 +88,11 @@
  *   variables specific to the particular theme hook.
  *
  * @subsection sub_preprocess_theme_funcs Preprocessing for Theme Functions
- * If the implementation is a function, only the theme-hook-specific preprocess
- * functions (the ones ending in _HOOK) are called from the list above. This is
- * because theme hooks with function implementations need to be fast, and
- * calling the non-theme-hook-specific preprocess functions for them would incur
- * a noticeable performance penalty.
+ * If the theming implementation is a function, only the theme-hook-specific
+ * preprocess functions (the ones ending in _HOOK) are called from the list
+ * above. This is because theme hooks with function implementations need to be
+ * fast, and calling the non-theme-hook-specific preprocess functions for them
+ * would incur a noticeable performance penalty.
  *
  * @subsection sub_alternate_suggestions Suggesting Alternate Hooks
  * Alternate hooks can be suggested by implementing the hook-specific
@@ -102,9 +102,10 @@
  * priority. _theme() will use the highest priority implementation that exists.
  * If none exists, _theme() will use the implementation for the theme hook it
  * was called with. These suggestions are similar to and are used for similar
- * reasons as calling _theme() with an array as the $hook parameter (see below).
- * The difference is whether the suggestions are determined by the code that
- * calls _theme() or by altering the suggestions via the suggestion alter hooks.
+ * reasons as assigning an array of theme hooks to the #theme property of a
+ * renderable array. The difference is whether the suggestions are determined
+ * when _theme() is called or through altering the suggestions via the
+ * suggestion alter hooks.
  *
  * @see drupal_render()
  * @see _theme()