diff --git a/core/modules/system/theme.api.php b/core/modules/system/theme.api.php
index 34758da..fce243a 100644
--- a/core/modules/system/theme.api.php
+++ b/core/modules/system/theme.api.php
@@ -158,51 +158,77 @@ function hook_preprocess_HOOK(&$variables) {
 }
 
 /**
- * Provides alternate named suggestions for a specific theme hook.
- *
- * This hook allows the module implementing hook_theme() for a theme hook to
- * provide alternative theme function or template name suggestions. This hook is
- * only invoked for the first module implementing hook_theme() for a theme hook.
- *
- * HOOK is the least-specific version of the hook being called. For example, if
- * '#theme' => 'node__article' is called, then node_theme_suggestions_node()
- * will be invoked, not node_theme_suggestions_node__article(). The specific
- * hook called (in this case 'node__article') is available in
- * $variables['theme_hook_original'].
- *
- * @todo Add @code sample.
+ * Provides more specific templates or theme functions for a theme hook.
+ *
+ * These alternative template or theme functions can optionally be used by a
+ * theme to override markup or display logic based on incoming variables or
+ * global context.
+ *
+ * For a specific theme hook like 'node', this hook allows the module providing
+ * the theme hook (the module implementing hook_theme()) to provide more
+ * specific template name suggestions, for example node--front.html.twig for a
+ * node displayed on the front page, or node--article.html.twig for an article
+ * node.
+ *
+ * HOOK is the least-specific version of the hook being called, also known as
+ * the base theme hook. For example, if '#theme' => 'node__article' is called,
+ * then node_theme_suggestions_node() will be invoked, not
+ * node_theme_suggestions_node__article(). The specific hook called (in this
+ * case 'node__article') is available in $variables['theme_hook_original'].
+ *
+ * Note that this hook is not invoked for themes, even if the theme implements
+ * hook_theme(). Themes must use hook_theme_suggestions_HOOK_alter().
+ *
+ * The following example provides an optional block--not-front.html.twig
+ * template that could be used to change the markup or display logic for blocks
+ * shown on every page but the front page:
+ * @code
+ * function block_theme_suggestions_block(array $variables) {
+ *   $suggestions = array();
+ *   if (!drupal_is_front_page()) {
+ *     $suggestions[] = 'block__not_front';
+ *   }
+ *   return $suggestions;
+ * }
+ * @endcode
  *
  * @param array $variables
  *   An array of variables passed to the theme hook. Note that this hook is
- *   invoked before any preprocessing.
+ *   invoked before any variable preprocessing.
  *
  * @return array
- *   An array of theme suggestions.
+ *   An array of alternate, more specific names for template files or theme
+ *   functions.
  *
  * @see hook_theme_suggestions_HOOK_alter()
  */
 function hook_theme_suggestions_HOOK(array $variables) {
   $suggestions = array();
-
+  // If the node language is French, this would provide node--fr.html.twig as an
+  // optional template override for French nodes.
   $suggestions[] = 'node__' . $variables['elements']['#langcode'];
 
   return $suggestions;
 }
 
 /**
- * Alters named suggestions for a specific theme hook.
+ * Alters available templates or theme function names for a theme hook.
  *
  * This hook allows any module or theme to provide altenative theme function or
  * template name suggestions and reorder or remove suggestions provided by
  * hook_theme_suggestions_HOOK() or by earlier invocations of this hook.
  *
- * HOOK is the least-specific version of the hook being called. For example, if
- * '#theme' => 'node__article' is called, then node_theme_suggestions_node()
- * will be invoked, not node_theme_suggestions_node__article(). The specific
- * hook called (in this case 'node__article') is available in
- * $variables['theme_hook_original'].
- *
- * @todo Add @code sample.
+ * HOOK is the least-specific version of the hook being called, also known as
+ * the base theme hook. For example, if '#theme' => 'node__article' is called,
+ * then node_theme_suggestions_node() will be invoked, not
+ * node_theme_suggestions_node__article(). The specific hook called (in this
+ * case 'node__article') is available in $variables['theme_hook_original'].
+ *
+ * Here's a good example of altering suggestions. Maybe this example should also
+ * manipulate the order of suggestions?
+ * @code
+ * ...
+ * @endcode
  *
  * @param array $suggestions
  *   An array of theme suggestions.