diff --git a/core/modules/block/block.admin.inc b/core/modules/block/block.admin.inc
index 6edf8ee..0bbadf2 100644
--- a/core/modules/block/block.admin.inc
+++ b/core/modules/block/block.admin.inc
@@ -237,18 +237,19 @@ function _block_compare($ainstance, $binstance) {
 }
 
 /**
- * Form constructor for the block configuration form.
+ * Form constructor for the block instance configuration form.
  *
- * Also used by block_add_block_form() for adding a new custom block.
- *
- * @param $module
- *   Name of the module that implements the block to be configured.
- * @param $delta
- *   Unique ID of the block within the context of $module.
+ * @param string $plugin_id
+ *   The plugin ID for the block instance.
+ * @param string $theme
+ *   (optional) The name of the theme for the block instance. If no theme is
+ *   specified, the default theme will be used.
  *
  * @see block_menu()
+ * @see custom_block_menu()
  * @see block_admin_configure_validate()
  * @see block_admin_configure_submit()
+ *
  * @ingroup forms
  */
 function block_admin_configure($form, &$form_state, $plugin_id, $theme = NULL) {
@@ -301,11 +302,14 @@ function block_admin_configure_submit($form, &$form_state) {
 /**
  * Form constructor for the custom block deletion form.
  *
- * @param $module
- *   The name of the module that implements the block to be deleted. This should
- *   always equal 'block' since it only allows custom blocks to be deleted.
- * @param $delta
- *   The unique ID of the block within the context of $module.
+ * @param string $plugin_id
+ *   The plugin ID for the block instance.
+ * @param string $theme
+ *   The name of the theme for the block instance.
+ *
+ * @todo Is this form still only for custom blocks? If so, should it and its
+ *    handlers be moved to custom_block.module? If not, the documentation
+ *    should be corrected.
  *
  * @see block_menu()
  * @see block_admin_block_delete_submit()
diff --git a/core/modules/block/block.api.php b/core/modules/block/block.api.php
index 01abf16..defde15 100644
--- a/core/modules/block/block.api.php
+++ b/core/modules/block/block.api.php
@@ -54,7 +54,11 @@ function hook_block_view_alter(array &$build, \Drupal\block\BlockInterface $bloc
  * @param \Drupal\block\BlockInterface $block
  *   The block instance.
  *
+ * @todo Add a more specific example of a block ID, and illustrate how this is
+ *   different from hook_block_view_NAME_alter().
+ *
  * @see hook_block_view_alter()
+ * @see hook_block_view_NAME_alter()
  */
 function hook_block_view_ID_alter(array &$build, \Drupal\block\BlockInterface $block) {
   // This code will only run for a specific block. For example, if ID
@@ -78,7 +82,12 @@ function hook_block_view_ID_alter(array &$build, \Drupal\block\BlockInterface $b
  * @param \Drupal\block\BlockInterface $block
  *   The block instance.
  *
+ * @todo NAME is ambiguous, and so is the example here. Use a more specific
+ *   example to illustrate what the block instance name will look like, and
+ *   also illustrate how it is different from hook_block_view_ID().
+ *
  * @see hook_block_view_alter()
+ * @see hook_block_view_ID_alter()
  */
 function hook_block_view_NAME_alter(array &$build, \Drupal\block\BlockInterface $block) {
   // This code will only run for a specific block instance. For example, if NAME
diff --git a/core/modules/block/block.module b/core/modules/block/block.module
index f242d6d..137e2ed 100644
--- a/core/modules/block/block.module
+++ b/core/modules/block/block.module
@@ -106,6 +106,8 @@ function block_permission() {
 
 /**
  * Implements hook_menu().
+ *
+ * @todo Clarify the documentation for the per-plugin block admin links.
  */
 function block_menu() {
   $default_theme = variable_get('theme_default', 'stark');
@@ -460,13 +462,13 @@ function block_list($region) {
 }
 
 /**
- * Loads a block object from the database.
+ * Loads a block instance.
  *
  * @param string $plugin_id
  *   The plugin ID to load.
  * @param array $conf
- *   An optional configuration array for creating a block instance from php
- *   instead of relying on configuration xml.
+ *   An optional configuration array for creating a block instance manually
+ *   rather than retrieving it from the configuration system.
  *
  * @return
  *   A block object.
@@ -538,6 +540,7 @@ function _block_get_renderable_block($element) {
  *   - #title: The default localized title of the block.
  *
  * @todo Move the alter invocation into a plugin method.
+ * @todo Add specific examples of $id and $name below.
  */
 function block_build($block) {
   // Allow modules to modify the block before it is viewed, via either
diff --git a/core/modules/block/custom_block/custom_block.admin.inc b/core/modules/block/custom_block/custom_block.admin.inc
index 9b8bd52..57017e1 100644
--- a/core/modules/block/custom_block/custom_block.admin.inc
+++ b/core/modules/block/custom_block/custom_block.admin.inc
@@ -12,14 +12,14 @@ function custom_block_admin_custom_block($form, &$form_state) {
   $destination = drupal_get_destination();
    $header = array(
     'info' => array(
-      'data' => t('Administrative Title'),
+      'data' => t('Administrative title'),
       'field' => 'cb.info',
     ),
     'operations' => array(
       'data' => t('Operations')
     )
   );
-  $header = array(t('Administrative Title'), t('Operations'));
+  $header = array(t('Administrative title'), t('Operations'));
   $options = array();
   $results = db_query('SELECT * FROM {block_custom}');
   foreach ($results as $result) {
diff --git a/core/modules/block/custom_block/custom_block.info b/core/modules/block/custom_block/custom_block.info
index f9e8f05..3dafb61 100644
--- a/core/modules/block/custom_block/custom_block.info
+++ b/core/modules/block/custom_block/custom_block.info
@@ -1,5 +1,5 @@
 name = Custom Block
-description = Allows the ability to create custom blocks through the block interface.
+description = Allows the creaation of custom blocks through the user interface.
 package = Core
 version = VERSION
 core = 8.x
diff --git a/core/modules/block/custom_block/custom_block.module b/core/modules/block/custom_block/custom_block.module
index b93b96e..27b1a10 100644
--- a/core/modules/block/custom_block/custom_block.module
+++ b/core/modules/block/custom_block/custom_block.module
@@ -2,11 +2,13 @@
 
 /**
  * @file
- * Allows the ability to create custom blocks through the block interface.
+ * Allows the creaation of custom blocks through the user interface.
  */
 
 /**
  * Implements hook_menu().
+ *
+ * @todo Clarify documentation here about what menu items are being added.
  */
 function custom_block_menu() {
   $items = array();
@@ -15,7 +17,7 @@ function custom_block_menu() {
     if (strpos($plugin_id, 'block_plugin_ui') === 0) {
       list(, $theme) = explode(':', $plugin_id);
       $items['admin/structure/block/list/' . $plugin_id . '/add/custom_blocks'] = array(
-        'title' => 'Add Custom Block',
+        'title' => 'Add custom block',
         'description' => 'Create a block with custom content and settings.',
         'page callback' => 'drupal_get_form',
         'page arguments' => array('block_admin_configure', 'custom_block:custom_block', $theme),
@@ -25,8 +27,8 @@ function custom_block_menu() {
         'file path' => drupal_get_path('module', 'block'),
       );
       $items['admin/structure/block/list/' . $plugin_id . '/add/custom_blocks_library'] = array(
-        'title' => 'Custom Blocks',
-        'description' => 'Administrate custom blocks content.',
+        'title' => 'Custom blocks',
+        'description' => 'Administer custom block content.',
         'page callback' => 'drupal_get_form',
         'page arguments' => array('custom_block_admin_custom_block'),
         'access callback' => TRUE,
diff --git a/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/Derivative/CustomBlock.php b/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/Derivative/CustomBlock.php
index e3a5072..f8f5755 100644
--- a/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/Derivative/CustomBlock.php
+++ b/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/Derivative/CustomBlock.php
@@ -10,7 +10,7 @@
 use Drupal\Component\Plugin\Derivative\DerivativeInterface;
 
 /**
- * Provides block plugin definitions for all custom blocks.
+ * Retrieves block plugin definitions for all custom blocks.
  */
 class CustomBlock implements DerivativeInterface {
 
@@ -23,6 +23,8 @@ class CustomBlock implements DerivativeInterface {
 
   /**
    * Implements \Drupal\Component\Plugin\Derivative\DerivativeInterface::getDerivativeDefinition().
+   *
+   * Retrieves a specific custom block definition from storage.
    */
   public function getDerivativeDefinition($derivative_id, array $base_plugin_definition) {
     if (!empty($this->derivatives) && !empty($this->derivatives[$derivative_id])) {
@@ -34,6 +36,8 @@ public function getDerivativeDefinition($derivative_id, array $base_plugin_defin
 
   /**
    * Implements \Drupal\Component\Plugin\Derivative\DerivativeInterface::getDerivativeDefinitions().
+   *
+   * Retrieves custom block definitions from storage.
    */
   public function getDerivativeDefinitions(array $base_plugin_definition) {
     $results = db_query('SELECT * FROM {block_custom}');
@@ -45,6 +49,7 @@ public function getDerivativeDefinitions(array $base_plugin_definition) {
         'format' => $result->format,
       ) + $base_plugin_definition['settings'];
       $this->derivatives[$result->bid]['subject'] = $result->info;
+      // @todo Add an inline comment here explaining why we unset this key.
       unset($this->derivatives[$result->bid]['custom']);
     }
     $this->derivatives['custom_block'] = $base_plugin_definition;
diff --git a/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/block/block/CustomBlock.php b/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/block/block/CustomBlock.php
index 9155b54..18b13b8 100644
--- a/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/block/block/CustomBlock.php
+++ b/core/modules/block/custom_block/lib/Drupal/custom_block/Plugin/block/block/CustomBlock.php
@@ -11,7 +11,7 @@
 use Drupal\Core\Annotation\Translation;
 
 /**
- * Provides a generic custom block.
+ * Defines a generic custom block type.
  *
  * @Plugin(
  *  id = "custom_block",
@@ -44,6 +44,8 @@ public function getConfig() {
 
   /**
    * Overrides \Drupal\block\BlockBase::configure().
+   *
+   * Adds body and description fields to the block configuration form.
    */
   public function configure($form, &$form_state) {
     $form = parent::configure($form, $form_state);
diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 514fa9e..74b51e6 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -20,9 +20,13 @@
 
   /**
    * Implements \Drupal\block\BlockInterface::settingsWrapper().
+   *
+   * @todo This method is not actually on the interface. Add it there if it
+   *   should be required, or correct this documentation.
    */
   public function settingsWrapper() {
     $settings = $this->settings();
+    // By default, blocks are enabled and not cached.
     $settings += array(
       'status' => TRUE,
       'cache' => DRUPAL_NO_CACHE,
@@ -32,6 +36,9 @@ public function settingsWrapper() {
 
   /**
    * Implements \Drupal\block\BlockInterface::settings().
+   *
+   * Block plugins only need to implement this method if they override the
+   * defaults provided in BlockInterface::settingsWrapper().
    */
   public function settings() {
     return array();
@@ -39,6 +46,9 @@ public function settings() {
 
   /**
    * Implements \Drupal\block\BlockInterface::getConfig().
+   *
+   * @todo This method is not actually on the interface. Add it there if it
+   *   should be required, or correct this documentation.
    */
   public function getConfig() {
     if (empty($this->configuration)) {
@@ -53,94 +63,123 @@ public function getConfig() {
     return $this->configuration;
   }
 
+  /**
+   * @todo Document this method.
+   */
   public function setConfig($key, $value) {
     $this->configuration[$key] = $value;
   }
 
   /**
    * Implements \Drupal\block\BlockInterface::access().
+   *
+   * Block plugins should override this method to add access restrictions
+   * specific to the block type.
    */
   public function access() {
+    // By default, the block is visible unless user-configured rules indicate
+    // that it should be hidden.
     return TRUE;
   }
 
   /**
    * Implements \Drupal\block\BlockInterface::accessWrapper().
+   *
+   * Adds the user-configured per-role, per-path, and per-language visibility
+   * settings to all blocks, and invokes hook_block_access().
+   *
+   * Most plugins should not override this method unless they need to remove
+   * the user-defined access restrictions. To add specific access
+   * restrictions for a particular block type, override BlockBase::access()
+   * instead.
+   *
+   * @see hook_block_access()
    */
   public function accessWrapper() {
-    if ($this->access()) {
-      global $user, $theme_key;
-      // Status handling.
-      if (empty($this->configuration['status'])) {
-        return FALSE;
-      }
+    // If the block-specific access restrictions indicate the block is not
+    // accessible, always deny access.
+    if (!$this->access()) {
+      return FALSE;
+    }
 
-      // User Role Handling.
-      // If a block has no roles associated, it is displayed for every role.
-      // For blocks with roles associated, if none of the user's roles matches
-      // the settings from this block, access is denied.
-      if (!empty($this->configuration['visibility']['role']['roles']) && !array_intersect(array_filter($this->configuration['visibility']['role']['roles']), array_keys($user->roles))) {
-        // No match.
-        return FALSE;
-      }
+    // Otherwise, check for other access restrictions.
+    global $user, $theme_key;
 
-      // Page path handling.
-      // Limited visibility blocks must list at least one page.
-      if (!empty($this->configuration['visibility']['path']['visibility']) && $this->configuration['visibility']['path']['visibility'] == BLOCK_VISIBILITY_LISTED && empty($this->configuration['visibility']['path']['pages'])) {
-        return FALSE;
-      }
+    // Deny access to disabled blocks.
+    if (empty($this->configuration['status'])) {
+      return FALSE;
+    }
 
-      // Match path if necessary.
-      if (!empty($this->configuration['visibility']['path']['pages'])) {
-        // Assume there are no matches until one is found.
-        $page_match = FALSE;
-
-        // Convert path to lowercase. This allows comparison of the same path
-        // with different case. Ex: /Page, /page, /PAGE.
-        $pages = drupal_strtolower($this->configuration['visibility']['path']['pages']);
-        if ($this->configuration['visibility']['path']['visibility'] < BLOCK_VISIBILITY_PHP) {
-          // Compare the lowercase path alias (if any) and internal path.
-          $path = current_path();
-          $path_alias = drupal_strtolower(drupal_container()->get('path.alias_manager')->getPathAlias($path));
-          $page_match = drupal_match_path($path_alias, $pages) || (($path != $path_alias) && drupal_match_path($path, $pages));
-          // When $block->visibility has a value of 0
-          // (BLOCK_VISIBILITY_NOTLISTED), the block is displayed on all pages
-          // except those listed in $block->pages. When set to 1
-          // (BLOCK_VISIBILITY_LISTED), it is displayed only on those pages
-          // listed in $block->pages.
-          $page_match = !($this->configuration['visibility']['path']['visibility'] xor $page_match);
-        }
-        elseif (module_exists('php')) {
-          $page_match = php_eval($this->configuration['visibility']['path']['pages']);
-        }
+    // User role access handling.
+    // If a block has no roles associated, it is displayed for every role.
+    // For blocks with roles associated, if none of the user's roles matches
+    // the settings from this block, access is denied.
+    if (!empty($this->configuration['visibility']['role']['roles']) && !array_intersect(array_filter($this->configuration['visibility']['role']['roles']), array_keys($user->roles))) {
+      // No match.
+      return FALSE;
+    }
 
-        // If there are page visibility restrictions and this page does not
-        // match, deny access.
-        if (!$page_match) {
-          return FALSE;
-        }
+    // Page path handling.
+    // Limited visibility blocks must list at least one page.
+    if (!empty($this->configuration['visibility']['path']['visibility']) && $this->configuration['visibility']['path']['visibility'] == BLOCK_VISIBILITY_LISTED && empty($this->configuration['visibility']['path']['pages'])) {
+      return FALSE;
+    }
+
+    // Match path if necessary.
+    if (!empty($this->configuration['visibility']['path']['pages'])) {
+      // Assume there are no matches until one is found.
+      $page_match = FALSE;
+
+      // Convert path to lowercase. This allows comparison of the same path
+      // with different case. Ex: /Page, /page, /PAGE.
+      $pages = drupal_strtolower($this->configuration['visibility']['path']['pages']);
+      if ($this->configuration['visibility']['path']['visibility'] < BLOCK_VISIBILITY_PHP) {
+        // Compare the lowercase path alias (if any) and internal path.
+        $path = current_path();
+        $path_alias = drupal_strtolower(drupal_container()->get('path.alias_manager')->getPathAlias($path));
+        $page_match = drupal_match_path($path_alias, $pages) || (($path != $path_alias) && drupal_match_path($path, $pages));
+        // When $block->visibility has a value of 0
+        // (BLOCK_VISIBILITY_NOTLISTED), the block is displayed on all pages
+        // except those listed in $block->pages. When set to 1
+        // (BLOCK_VISIBILITY_LISTED), it is displayed only on those pages
+        // listed in $block->pages.
+        $page_match = !($this->configuration['visibility']['path']['visibility'] xor $page_match);
+      }
+      elseif (module_exists('php')) {
+        $page_match = php_eval($this->configuration['visibility']['path']['pages']);
       }
 
-      // Language visibility settings.
-      if (!empty($this->configuration['visibility']['language']['langcodes']) && array_filter($this->configuration['visibility']['language']['langcodes'])) {
-        if (empty($this->configuration['visibility']['language']['langcodes'][language($this->configuration['visibility']['language']['language_type'])->langcode])) {
-          return FALSE;
-        }
+      // If there are page visibility restrictions and this page does not
+      // match, deny access.
+      if (!$page_match) {
+        return FALSE;
       }
+    }
 
-      // Check other modules for block access rules.
-      foreach (module_implements('block_access') as $module) {
-        if (module_invoke($module, 'block_access', $this) === FALSE) {
-          return FALSE;
-        }
+    // Language visibility settings.
+    if (!empty($this->configuration['visibility']['language']['langcodes']) && array_filter($this->configuration['visibility']['language']['langcodes'])) {
+      if (empty($this->configuration['visibility']['language']['langcodes'][language($this->configuration['visibility']['language']['language_type'])->langcode])) {
+        return FALSE;
       }
-      return TRUE;
     }
-    return FALSE;
+
+    // Check other modules for block access rules.
+    foreach (module_implements('block_access') as $module) {
+      if (module_invoke($module, 'block_access', $this) === FALSE) {
+        return FALSE;
+      }
+    }
+
+    // If nothing denied access to the block, it is accessible.
+    return TRUE;
   }
 
   /**
    * Implements \Drupal\block\BlockInterface::configureWrapper().
+   *
+   * Creates a generic configuration form for all block types. Individual
+   * block plugins can add elements to this form by implementing
+   * BlockInterface::configure().
    */
   public function configureWrapper($form, &$form_state) {
     $definition = $this->getDefinition();
@@ -198,10 +237,9 @@ public function configureWrapper($form, &$form_state) {
     $themes = list_themes();
     $key = $form['theme']['#value'];
     $theme = $themes[$key];
-    // Only display enabled themes
+    // Only display enabled themes.
     if ($theme->status) {
-      // Use a meaningful title for the main site theme and administrative
-      // theme.
+      // Use meaningful titles for the main site and administrative themes.
       $theme_title = $theme->info['name'];
       if ($key == $theme_default) {
         $theme_title = t('!theme (default theme)', array('!theme' => $theme_title));
@@ -345,6 +383,7 @@ public function configureWrapper($form, &$form_state) {
       '#description' => t('Show this block only for the selected role(s). If you select no roles, the block will be visible to all users.'),
     );
 
+    // Add specific configuration for this block type.
     $form += $this->configure($form, $form_state);
 
     $form['actions'] = array('#type' => 'actions');
@@ -365,6 +404,8 @@ public function configure($form, &$form_state) {
 
   /**
    * Implements \Drupal\block\BlockInterface::configureValidateWrapper().
+   *
+   * @todo Add inline documentation to this method.
    */
   public function configureValidateWrapper($form, &$form_state) {
     if (empty($form['settings']['machine_name']['#disabled'])) {
@@ -389,6 +430,8 @@ public function configureValidateWrapper($form, &$form_state) {
       }
     }
     $form_state['values']['visibility']['role']['roles'] = array_filter($form_state['values']['visibility']['role']['roles']);
+
+    // Validate block type-specific form elements.
     $this->configureValidate($form, $form_state);
   }
 
@@ -399,6 +442,8 @@ public function configureValidate($form, &$form_state) {}
 
   /**
    * Implements \Drupal\block\BlockInterface::configureSubmitWrapper().
+   *
+   * @todo Add inline documentation to this method.
    */
   public function configureSubmitWrapper($form, &$form_state) {
     if (!form_get_errors()) {
@@ -428,6 +473,8 @@ public function configureSubmitWrapper($form, &$form_state) {
       }
       drupal_set_message(t('The block configuration has been saved.'));
       drupal_flush_all_caches();
+
+      // Handle submissions for block type-specific form elements.
       $this->configureSubmit($form, $form_state);
     }
   }
diff --git a/core/modules/block/lib/Drupal/block/BlockInterface.php b/core/modules/block/lib/Drupal/block/BlockInterface.php
index c152ea2..d0ab023 100644
--- a/core/modules/block/lib/Drupal/block/BlockInterface.php
+++ b/core/modules/block/lib/Drupal/block/BlockInterface.php
@@ -7,7 +7,14 @@
 namespace Drupal\block;
 
 /**
- * Interface definition for Block plugins.
+ * Defines the required interface for all block plugins.
+
+ * @todo Add detailed documentation here explaining the block system's
+ *   architecture and the relationships between the various objects, including
+ *   brif references to the important components that are not coupled to the
+ *   interface.
+ *
+ * @see \Drupal\block\BlockBase
  */
 interface BlockInterface {
 
@@ -15,55 +22,96 @@
    * Returns the default settings for this block plugin.
    *
    * @return array
+   *   An associative array of block settings for this block, keyed by the
+   *   setting name.
    */
   public function settings();
 
   /**
-   * Indicates whether the block should be shown, based on general criteria.
-   *
-   * This method should enforce the general contracts that are generally
-   * applicable to all blocks: role, path, and page-based visibility settings.
+   * Indicates whether the block should be shown.
    *
-   * This is the method that is typically called externally, so implementations
-   * of it should make sure to also call BlockInterface::access() and AND the
-   * result with their own result to provide the final access determination.
+   * This method allows base implementations to add general access restrictions
+   * that should apply to all extending block plugins, and is typically the
+   * access check used externally. Base implementations of this method should
+   * generally check BlockInterface::access() so that extending classes can
+   * add their own access restrictions.
    *
    * @return bool
+   *   TRUE if the block should be shown, or FALSE otherwise.
+   *
+   * @see \Drupal\block\BlockInterace::access()
    */
   public function accessWrapper();
 
   /**
-   * Indicates whether the block should be shown, based on internal criteria.
+   * Indicates whether block-specific criteria allow access to the block.
    *
-   * Blocks with access control that should *always* be applied, regardless of
-   * user-configured settings, should implement this method with that access
-   * control logic.
+   * Blocks with access restrictions that should always be applied,
+   * regardless of user-configured settings, should implement this method
+   * with that access control logic.
    *
    * @return bool
+   *   FALSE to deny access to the block, or TRUE to allow
+   *   BlockInterface::accessWrapper() to make the access determination.
+   *
+   * @see \Drupal\block\BlockInterace::accessWrapper()
    */
   public function access();
 
   /**
    * Returns the configuration form elements specific to this block plugin.
    *
+   * Blocks that need to add form elements to the normal block configuration
+   * form should implement this method.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
+   *
    * @return array $form
+   *   The renderable form array representing the entire configuration form.
+   *
+   * @see \Drupal\block\BlockInterace::configureWrapper()
    */
   public function configure($form, &$form_state);
 
   /**
    * The validation wrapper for the configuration form.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
+   *
+   * @todo Clarify documentation for this method.
    */
   public function configureValidate($form, &$form_state);
 
   /**
    * The submission wrapper for the configuration form.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
+   *
+   * @todo Clarify documentation for this method.
    */
   public function configureSubmit($form, &$form_state);
 
   /**
    * Returns the full form for block configuration.
    *
-   * This incorporates both
+   * This method allows base implementations to add a generic configuration
+   * form for extending block plugins. Base implementations of this method
+   * should generally embed the result of BlockInterface::configure() in the
+   * form so that extending classes can add their own configuration options.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
    *
    * @return array $form
    *   The renderable form array representing the entire configuration form.
@@ -72,11 +120,27 @@ public function configureWrapper($form, &$form_state);
 
   /**
    * The validation for the configuration form.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
+   *
+   * @see \Drupal\block\BlockInterace::configure()
+   *
+   * @todo Clarify documentation for this method.
    */
   public function configureValidateWrapper($form, &$form_state);
 
   /**
    * The submission for the configuration form.
+   *
+   * @param array $form
+   *   The form definition array for the block configuration form.
+   * @param array $form_state
+   *   An array containing the current state of the configuration form.
+   *
+   * @todo Clarify documentation for this method.
    */
   public function configureSubmitWrapper($form, &$form_state);
 
diff --git a/core/modules/block/lib/Drupal/block/Plugin/Derivative/BlockPluginUI.php b/core/modules/block/lib/Drupal/block/Plugin/Derivative/BlockPluginUI.php
index 7762a7f..30853ce 100644
--- a/core/modules/block/lib/Drupal/block/Plugin/Derivative/BlockPluginUI.php
+++ b/core/modules/block/lib/Drupal/block/Plugin/Derivative/BlockPluginUI.php
@@ -10,6 +10,9 @@
 
 /**
  * Provides block plugin definitions for each theme.
+ *
+ * @todo This class is either misnamed or mis-documented.
+ * @todo Add documentation to this class.
  */
 class BlockPluginUI implements DerivativeInterface {
 
@@ -22,6 +25,8 @@ class BlockPluginUI implements DerivativeInterface {
 
   /**
    * Implements \Drupal\Component\Plugin\Derivative\DerivativeInterface::getDerivativeDefinition().
+   *
+   * @todo Add documentation to this method.
    */
   public function getDerivativeDefinition($derivative_id, array $base_plugin_definition) {
     if (!empty($this->derivatives) && !empty($this->derivatives[$derivative_id])) {
@@ -33,6 +38,8 @@ public function getDerivativeDefinition($derivative_id, array $base_plugin_defin
 
   /**
    * Implements \Drupal\Component\Plugin\Derivative\DerivativeInterface::getDerivativeDefinitions().
+   *
+   * @todo Add documentation to this method.
    */
   public function getDerivativeDefinitions(array $base_plugin_definition) {
     foreach (list_themes() as $key => $theme) {
diff --git a/core/modules/block/lib/Drupal/block/Plugin/Type/BlockManager.php b/core/modules/block/lib/Drupal/block/Plugin/Type/BlockManager.php
index 5430c2b..49b3ee3 100644
--- a/core/modules/block/lib/Drupal/block/Plugin/Type/BlockManager.php
+++ b/core/modules/block/lib/Drupal/block/Plugin/Type/BlockManager.php
@@ -15,6 +15,10 @@
 
 /**
  * Manages discovery and instantiation of block plugins.
+ *
+ * @todo Add documentation to this class.
+ *
+ * @see \Drupal\block\BlockInterface
  */
 class BlockManager extends PluginManagerBase {
 
diff --git a/core/modules/block/lib/Drupal/block/Plugin/system/plugin_ui/BlockPluginUI.php b/core/modules/block/lib/Drupal/block/Plugin/system/plugin_ui/BlockPluginUI.php
index 0213023..e7ffc2c 100644
--- a/core/modules/block/lib/Drupal/block/Plugin/system/plugin_ui/BlockPluginUI.php
+++ b/core/modules/block/lib/Drupal/block/Plugin/system/plugin_ui/BlockPluginUI.php
@@ -39,8 +39,11 @@ class BlockPluginUI extends PluginUIBase {
 
   /**
    * Overrides \Drupal\system\Plugin\PluginUIBase::form().
+   *
+   * @todo Add inline documentation to this method.
    */
   public function form($form, &$form_state, $facet = NULL) {
+    // @todo Add an inline comment here.
     $plugin_definition = $this->getDefinition();
     $manager = new $plugin_definition['manager']();
     $plugins = $this->excludeDefinitions($manager->getDefinitions());
diff --git a/core/modules/block/lib/Drupal/block/Tests/BlockLanguageTest.php b/core/modules/block/lib/Drupal/block/Tests/BlockLanguageTest.php
index 842825d..2fa1d40 100644
--- a/core/modules/block/lib/Drupal/block/Tests/BlockLanguageTest.php
+++ b/core/modules/block/lib/Drupal/block/Tests/BlockLanguageTest.php
@@ -99,17 +99,19 @@ public function testLanguageBlockVisibilityLanguageDelete() {
     );
     $this->drupalPost('admin/structure/block/manage/system_powered_by_block' . '/' . $default_theme, $edit, t('Save block'));
 
-    // Check that we have the language in config fter saving the setting.
+    // Check that we have the language in config after saving the setting.
     $config = config('plugin.core.block.' . $default_theme . '.language_block_test');
     $setting = $config->get('visibility.language.langcodes.fr');
-    $this->assertTrue('fr' === $setting, 'Language was set in the block config.');
+    $this->assertTrue('fr' === $setting, 'Language is set in the block configuration.');
 
     // Delete the language.
     $this->drupalPost('admin/config/regional/language/delete/fr', array(), t('Delete'));
 
-    // Check that we have the language in config fter saving the setting.
+    // Check that the language is no longer stored in the configuration after
+    // it is deleted.
     $config = config('plugin.core.block.' . $default_theme . '.language_block_test');
     $setting = $config->get('visibility.language.langcodes.fr');
-    $this->assertFalse('fr' === $setting, 'Language was not set in the block config.');
+    $this->assertTrue(empty($setting), 'Language is no longer not set in the block configuration after deleting the block.');
   }
+
 }
diff --git a/core/modules/block/lib/Drupal/block/Tests/BlockTemplateSuggestionsUnitTest.php b/core/modules/block/lib/Drupal/block/Tests/BlockTemplateSuggestionsUnitTest.php
index 8a1b241..fd75adf 100644
--- a/core/modules/block/lib/Drupal/block/Tests/BlockTemplateSuggestionsUnitTest.php
+++ b/core/modules/block/lib/Drupal/block/Tests/BlockTemplateSuggestionsUnitTest.php
@@ -36,6 +36,7 @@ function testBlockThemeHookSuggestions() {
     // Define a block with a derivative to be preprocessed, which includes both
     // an underscore (not transformed) and a hyphen (transformed to underscore),
     // and generates possibilities for each level of derivative.
+    // @todo Clarify this comment.
     $data = array(
       'region' => 'footer',
     );
diff --git a/core/modules/block/lib/Drupal/block/Tests/BlockTest.php b/core/modules/block/lib/Drupal/block/Tests/BlockTest.php
index 2ba3c55..59ed457 100644
--- a/core/modules/block/lib/Drupal/block/Tests/BlockTest.php
+++ b/core/modules/block/lib/Drupal/block/Tests/BlockTest.php
@@ -86,7 +86,7 @@ public function testCustomBlock() {
 
     // Confirm that the add block link appears on block overview pages.
     $this->drupalGet("admin/structure/block/list/block_plugin_ui:$default_theme/add");
-    $this->assertLink(t('Add Custom Block'));
+    $this->assertLink(t('Add custom block'));
 
     // Confirm that hidden regions are not shown as options for block placement
     // when adding a new block.
@@ -299,6 +299,7 @@ function testBlock() {
     $this->assertNoText(t($block['title']), 'Block no longer appears on page.');
 
     // Confirm that the region's xpath is not available.
+    // @todo Add a comment describing the pattern that the xpath is matching.
     $xpath = $this->buildXPathQuery('//div[@id=:id]/*', array(':id' => 'block-' . strtr(strtolower($block['machine_name']), '-', '_')));
     $this->assertNoFieldByXPath($xpath, FALSE, t('Block found in no regions.'));
   }
diff --git a/core/modules/system/lib/Drupal/system/Plugin/Type/PluginUIManager.php b/core/modules/system/lib/Drupal/system/Plugin/Type/PluginUIManager.php
index 28725f4..531a149 100644
--- a/core/modules/system/lib/Drupal/system/Plugin/Type/PluginUIManager.php
+++ b/core/modules/system/lib/Drupal/system/Plugin/Type/PluginUIManager.php
@@ -25,7 +25,10 @@ class PluginUIManager extends PluginManagerBase {
    * Constructs a \Drupal\system\Plugin\Type\PluginUIManager object.
    */
   public function __construct() {
-    $this->discovery = new CacheDecorator(new AlterDecorator(new DerivativeDiscoveryDecorator(new AnnotatedClassDiscovery('system', 'plugin_ui')), 'plugin_ui'), 'plugin_ui');
+    $this->discovery = new AnnotatedClassDiscovery('system', 'plugin_ui');
+    $this->discovery = new DerivativeDiscoveryDecorator($this->discovery);
+    $this->discovery = new AlterDecorator($this->discovery, 'plugin_ui');
+    $this->discovery = new CacheDecorator($this->discovery, 'plugin_ui');
     $this->factory = new DefaultFactory($this);
   }