diff --git a/core/includes/common.inc b/core/includes/common.inc
index 6bb5190..e436500 100644
--- a/core/includes/common.inc
+++ b/core/includes/common.inc
@@ -104,11 +104,16 @@ const JS_SETTING = 200;
 const HTTP_REQUEST_TIMEOUT = -1;
 
 /**
- * Constants defining cache granularity for blocks and renderable arrays.
+ * The block should not get cached.
+ *
+ * This setting should be used:
+ * - For simple blocks (notably those that do not perform any db query), where
+ *   querying the db cache would be more expensive than directly generating the
+ *   content.
+ * - For blocks that change too frequently.
  *
  * Modules specify the caching patterns for their blocks using binary
- * combinations of these constants in their hook_block_info():
- *   $block[delta]['cache'] = DRUPAL_CACHE_PER_ROLE | DRUPAL_CACHE_PER_PAGE;
+ * combinations of these constants in their hook_block_info().
  * DRUPAL_CACHE_PER_ROLE is used as a default when no caching pattern is
  * specified. Use DRUPAL_CACHE_CUSTOM to disable standard block cache and
  * implement
@@ -121,16 +126,6 @@ const HTTP_REQUEST_TIMEOUT = -1;
  *
  * Note that user 1 is excluded from block caching.
  */
-
-/**
- * The block should not get cached.
- *
- * This setting should be used:
- * - For simple blocks (notably those that do not perform any db query), where
- *   querying the db cache would be more expensive than directly generating the
- *   content.
- * - For blocks that change too frequently.
- */
 const DRUPAL_NO_CACHE = -1;
 
 /**
@@ -139,6 +134,8 @@ const DRUPAL_NO_CACHE = -1;
  * From the perspective of the block cache system, this is equivalent to
  * DRUPAL_NO_CACHE. Useful when time based expiration is needed or a site uses
  * a node access which invalidates standard block cache.
+ *
+ * @see DRUPAL_NO_CACHE
  */
 const DRUPAL_CACHE_CUSTOM = -2;
 
@@ -147,6 +144,8 @@ const DRUPAL_CACHE_CUSTOM = -2;
  *
  * This is the default setting for blocks, used when the block does not specify
  * anything.
+ *
+ * @see DRUPAL_NO_CACHE
  */
 const DRUPAL_CACHE_PER_ROLE = 0x0001;
 
@@ -155,16 +154,22 @@ const DRUPAL_CACHE_PER_ROLE = 0x0001;
  *
  * This setting can be resource-consuming for sites with large number of users,
  * and thus should only be used when DRUPAL_CACHE_PER_ROLE is not sufficient.
+ *
+ * @see DRUPAL_NO_CACHE
  */
 const DRUPAL_CACHE_PER_USER = 0x0002;
 
 /**
  * The block or element can change depending on the page being viewed.
+ *
+ * @see DRUPAL_NO_CACHE
  */
 const DRUPAL_CACHE_PER_PAGE = 0x0004;
 
 /**
  * The block or element is the same for every user and page that it is visible.
+ *
+ * @see DRUPAL_NO_CACHE
  */
 const DRUPAL_CACHE_GLOBAL = 0x0008;
 
diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 858a21b..b734685 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -55,6 +55,7 @@
  *       being viewed.
  *     - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
  *       page where it is visible.
+ *     - DRUPAL_CACHE_CUSTOM: The module implements its own caching system.
  *     - DRUPAL_NO_CACHE: The block should not get cached.
  *   - properties: (optional) Array of additional metadata to add to the block.
  *     Common properties include: