Issue #863428 by Albert Volkman, Mile23: Fix up block cache constant docs

core/includes/common.inc

@@ -104,11 +104,12 @@ const JS_SETTING = 200;
 const HTTP_REQUEST_TIMEOUT = -1;
 
 /**
- * Constants defining cache granularity for blocks and renderable arrays.
+ * @defgroup block_caching Block Caching
+ * @{
+ * Constants that define each block's caching state.
  *
  * 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
@@ -168,6 +169,10 @@ const DRUPAL_CACHE_PER_PAGE = 0x0004;
  */
 const DRUPAL_CACHE_GLOBAL = 0x0008;
 
+/**
+ * @} End of "defgroup block_caching".
+ */
+
 /**
  * The delimiter used to split plural strings.
  *

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: