diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 4a5abc8..ff49054 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -286,7 +286,11 @@ function hook_block_view_alter(&$data, $block) {
  * Perform alterations to a specific block.
  *
  * Modules can implement hook_block_view_MODULE_DELTA_alter() to modify a
- * specific block, rather than implementing hook_block_view_alter().
+ * specific block, rather than implementing hook_block_view_alter(). For
+ * example, if MODULE_DELTA were replaced with "mymodule_somedelta" in the
+ * function definition (i.e. hook_block_view_mymodule_somedelta_alter()), the
+ * code would only run on the "somedelta" block provided by the "mymodule"
+ * module.
  *
  * @param array $data
  *   An array of data, as returned from the hook_block_view() implementation of
@@ -305,10 +309,6 @@ function hook_block_view_alter(&$data, $block) {
  * @see hook_block_view()
  */
 function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
-  // This code will only run for a specific block. For example, if MODULE_DELTA
-  // in the function definition above is set to "mymodule_somedelta", the code
-  // will only run on the "somedelta" block provided by the "mymodule" module.
-
   // Change the title of the "somedelta" block provided by the "mymodule"
   // module.
   $data['subject'] = t('New title of the block');
@@ -325,15 +325,15 @@ function hook_block_view_MODULE_DELTA_alter(&$data, $block) {
  * You can also set $block->content here, which will override the content of the
  * block and prevent hook_block_view() from running.
  *
+ * This example shows how to achieve language specific visibility setting for
+ * blocks.
+ *
  * @param array $blocks
  *   An array of $blocks, keyed by the block ID.
  */
 function hook_block_list_alter(&$blocks) {
   global $language_interface, $theme_key;
 
-  // This example shows how to achieve language specific visibility setting for
-  // blocks.
-
   $result = db_query('SELECT module, delta, language FROM {my_table}');
   $block_languages = array();
   foreach ($result as $record) {