diff --git a/includes/common.inc b/includes/common.inc
index 8575844..868ffc5 100644
--- a/includes/common.inc
+++ b/includes/common.inc
@@ -92,37 +92,42 @@ define('JS_THEME', 100);
 define('HTTP_REQUEST_TIMEOUT', 1);
 
 /**
- * Constants defining cache granularity for blocks and renderable arrays.
+ * Drupal's cache granularity constants are used by both the block system and
+ * the array rendering system.
+ * 
+ * Granularity constants can be combined with a logical OR ("|") when used
+ * with array rendering. See drupal_render() for more details.
  *
- * 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;
- * 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
+ * DRUPAL_NO_CACHE specifies that no caching should occur. This setting
+ * should be used:
+ * - for simple blocks, where querying the db cache would be more expensive
+ * than directly generating the content.
+ * - for blocks that change too frequently to be cached effectively.
  *
- * The block cache is cleared in cache_clear_all(), and uses the same clearing
- * policy than page cache (node, comment, user, taxonomy added or updated...).
- * Blocks requiring more fine-grained clearing might consider disabling the
- * built-in block cache (DRUPAL_NO_CACHE) and roll their own.
+ * DRUPAL_NO_CACHE and DRUPAL_CACHE_CUSTOM are functionally equivalent.
  *
- * 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.
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_CACHE_CUSTOM
+ * @see DRUPAL_CACHE_PER_ROLE
+ * @see DRUPAL_CACHE_PER_USER
+ * @see DRUPAL_CACHE_PER_PAGE
+ * @see DRUPAL_CACHE_GLOBAL
  */
 define('DRUPAL_NO_CACHE', -1);
 
 /**
- * The block is handling its own caching in its hook_block_view(). 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.
+ * DRUPAL_CACHE_CUSTOM specifies that the block module has implemented its own
+ * caching system, and therefore Drupal core should not cache the block.
+ *
+ * DRUPAL_NO_CACHE and DRUPAL_CACHE_CUSTOM are functionally equivalent.
+ *
+ * Use DRUPAL_CACHE_CUSTOM when your module must implement its own caching
+ * system, such as for time-based expiration or special access rules.
+ *
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_NO_CACHE
  */
 define('DRUPAL_CACHE_CUSTOM', -2);
 
@@ -130,6 +135,12 @@ define('DRUPAL_CACHE_CUSTOM', -2);
  * The block or element can change depending on the roles the user viewing the
  * page belongs to. This is the default setting for blocks, used when the block
  * does not specify anything.
+ *
+ * See DRUPAL_NO_CACHE for more details.
+ *
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_NO_CACHE
  */
 define('DRUPAL_CACHE_PER_ROLE', 0x0001);
 
@@ -137,16 +148,34 @@ define('DRUPAL_CACHE_PER_ROLE', 0x0001);
  * The block or element can change depending on the user viewing the page.
  * 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 for more details.
+ *
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_NO_CACHE
  */
 define('DRUPAL_CACHE_PER_USER', 0x0002);
 
 /**
  * The block or element can change depending on the page being viewed.
+ *
+ * See DRUPAL_NO_CACHE for more details.
+ *
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_NO_CACHE
  */
 define('DRUPAL_CACHE_PER_PAGE', 0x0004);
 
 /**
  * The block or element is the same for every user on every page where it is visible.
+ *
+ * See DRUPAL_NO_CACHE for more details.
+ *
+ * @see drupal_render()
+ * @see hook_block_info()
+ * @see DRUPAL_NO_CACHE
  */
 define('DRUPAL_CACHE_GLOBAL', 0x0008);
 
diff --git a/modules/block/block.api.php b/modules/block/block.api.php
index d33f594..ede581a 100644
--- a/modules/block/block.api.php
+++ b/modules/block/block.api.php
@@ -56,6 +56,8 @@
  *     - DRUPAL_CACHE_GLOBAL: The block is the same for every user on every
  *       page where it is visible.
  *     - DRUPAL_NO_CACHE: The block should not get cached.
+ *     - DRUPAL_CACHE_CUSTOM: The module implements its own caching system.
+ *        This is functionally equivalent to DRUPAL_NO_CACHE.
  *   - 'properties': (optional) Array of additional metadata to add to the
  *     block. Common properties include:
  *     - 'administrative': Boolean which categorizes this block as usable in