core/includes/theme.inc | 48 +++++++++++++++++++++++++++++++++++++++++-------
 1 file changed, 41 insertions(+), 7 deletions(-)

diff --git a/core/includes/theme.inc b/core/includes/theme.inc
index f1162fb..cb7581e 100644
--- a/core/includes/theme.inc
+++ b/core/includes/theme.inc
@@ -320,15 +320,25 @@ function drupal_find_theme_templates($cache, $extension, $path) {
 }
 
 /**
- * Theme settings are an abomination, especially if they're used for things that
- * fundamentally aren't theme settings, but module or template settings. What's
- * worse is that this means that a preprocess function must itself bubble cache
- * tags, rather than setting it on a render array and letting that bubble it;
- * hence we end up with this monstrosity.
+ * For use in preprocess functions only; adds cache tags for theme settings.
+ *
+ * When a theme setting is used in a preprocess function, it is used to
+ * determine whether something should be visible or not. Hence the cache tags
+ * associated with that theme setting must *always* be added.
  *
  * Whenever theme_get_setting() is used in a preprocess function, this must also
  * be called, to ensure that the rendered HTML (and the render cache items that
  * contain this HTML) are tagged with the necessary cache tags.
+ *
+ * E.g.:
+ * @code
+ * theme_add_setting_cache_tag();
+ * if (theme_get_setting('features.node_user_picture')) {
+ *   $variables['author_picture'] = user_view($node->getOwner(), 'compact');
+ * }
+ * @endcode
+ *
+ * @see theme_get_setting()
  */
 function theme_add_setting_cache_tag() {
   $build = [
@@ -340,10 +350,31 @@ function theme_add_setting_cache_tag() {
 }
 
 /**
- * There's also no cheap way to figure out if it was the global theme settings
- * or a theme- specific overriding setting that wins, so we use both.
+ * Returns the cache tags to be used when using a theme setting.
+ *
+ * If a render array depends on a theme setting, then these cache tags should be
+ * associated with the render array.
+ *
+ * E.g.:
+ * @code
+ * $logo = theme_get_setting('logo');
+ * $build['site_logo'] = array(
+ *   '#theme' => 'image',
+ *   '#uri' => $logo['url'],
+ *   '#alt' => t('Home'),
+ *   '#access' => $this->configuration['use_site_logo'],
+ *   '#cache' => [
+ *     'tags' => theme_setting_get_cache_tags(),
+ *   ],
+ * );
+ * @endcode
+ *
+ * There's no efficient way to figure out if it was the global theme setting
+ * or a theme-specific overriding setting, so we return cache tags for both.
  *
  * @return string[]
+ *
+ * @see theme_get_setting()
  */
 function theme_setting_get_cache_tags() {
   $theme = \Drupal::theme()->getActiveTheme()->getName();
@@ -369,6 +400,9 @@ function theme_setting_get_cache_tags() {
  *
  * @return
  *   The value of the requested setting, NULL if the setting does not exist.
+ *
+ * @see theme_setting_get_cache_tags()
+ * @see theme_add_setting_cache_tag()
  */
 function theme_get_setting($setting_name, $theme = NULL) {
   /** @var \Drupal\Core\Theme\ThemeSettings[] $cache */