diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 7888b7b..4b616f2 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -121,8 +121,6 @@ public function blockForm($form, &$form_state) {
    * Most block plugins should not override this method. To add validation
    * for a specific block type, override BlockBase::blockValdiate().
    *
-   * @todo Add inline documentation to this method.
-   *
    * @see \Drupal\block\BlockBase::blockValidate()
    */
   public function validateConfigurationForm(array &$form, array &$form_state) {
@@ -140,11 +138,10 @@ public function blockValidate($form, &$form_state) {}
    * Most block plugins should not override this method. To add submission
    * handling for a specific block type, override BlockBase::blockSubmit().
    *
-   * @todo Add inline documentation to this method.
-   *
    * @see \Drupal\block\BlockBase::blockSubmit()
    */
   public function submitConfigurationForm(array &$form, array &$form_state) {
+    // Process the block's submission handling if no errors occurred only.
     if (!form_get_errors()) {
       $this->configuration['label'] = $form_state['values']['label'];
       $this->configuration['label_display'] = $form_state['values']['label_display'];
diff --git a/core/modules/block/lib/Drupal/block/BlockFormController.php b/core/modules/block/lib/Drupal/block/BlockFormController.php
index 3915315..4a4d1fb 100644
--- a/core/modules/block/lib/Drupal/block/BlockFormController.php
+++ b/core/modules/block/lib/Drupal/block/BlockFormController.php
@@ -299,9 +299,11 @@ public function validate(array $form, array &$form_state) {
       form_set_value($form['id'], $form_state['values']['theme'] . '.' . $form_state['values']['machine_name'], $form_state);
     }
     if (!empty($form['machine_name']['#disabled'])) {
+      // Get machine name from original value (without prepended theme name).
       $config_id = explode('.', $form_state['values']['machine_name']);
       $form_state['values']['machine_name'] = array_pop($config_id);
     }
+    // Remove empty lines from the role visibility list.
     $form_state['values']['visibility']['role']['roles'] = array_filter($form_state['values']['visibility']['role']['roles']);
     // The Block Entity form puts all block plugin form elements in the
     // settings form element, so just pass that to the block for validation.
@@ -331,6 +333,8 @@ public function submit(array $form, array &$form_state) {
     $entity->save();
 
     drupal_set_message($this->t('The block configuration has been saved.'));
+    // Invalidate the content cache and redirect to the block listing,
+    // because we need to remove cached block contents for each cache backend.
     Cache::invalidateTags(array('content' => TRUE));
     $form_state['redirect'] = array('admin/structure/block/list/' . $form_state['values']['theme'], array(
       'query' => array('block-placement' => drupal_html_class($this->entity->id())),