From fb7207f657a93b00480b986265be8ba1face3136 Mon Sep 17 00:00:00 2001
From: babruix <romanalexey@gmail.com>
Date: Tue, 19 Mar 2013 13:27:57 +0100
Subject: [PATCH] #1879396 by xjm: Added inline documentation to
 BlockBase::validate() and BlockBase::submit().

---
 core/modules/block/lib/Drupal/block/BlockBase.php | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 9c90a5a..7745181 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -414,22 +414,30 @@ public function blockForm($form, &$form_state) {
   /**
    * Implements \Drupal\block\BlockInterface::validate().
    *
-   * Most block plugins should not override this method. To add validation
-   * for a specific block type, override BlockBase::blockValdiate().
+   * Before sending the block to validation function BlockBase::blockValidate(),
+   * we need to prepare $form_state array:
+   * - Add machine_name to values array if if was not sent.
+   * - Clear empty values from roles list.
+   * - Set ID for new blocks.
    *
-   * @todo Add inline documentation to this method.
+   * Most block plugins should not override this method. To add validation
+   * for a specific block type, override BlockBase::blockValidate().
    *
    * @see \Drupal\block\BlockBase::blockValidate()
    */
   public function validate($form, &$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']);
     if ($form_state['entity']->isNew()) {
+      // Set ID for the block by concatenating the theme and the machine names.
       form_set_value($form['id'], $form_state['entity']->get('theme') . '.' . $form_state['values']['machine_name'], $form_state);
     }
+
     $this->blockValidate($form, $form_state);
   }
 
@@ -457,15 +465,16 @@ 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 submit($form, &$form_state) {
+    // Process the block's submission handling if there were no errors.
     if (!form_get_errors()) {
       $this->blockSubmit($form, $form_state);
 
       drupal_set_message(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_invalidate_tags(array('content' => TRUE));
       $form_state['redirect'] = 'admin/structure/block/list/block_plugin_ui:' . $form_state['entity']->get('theme');
     }
-- 
1.7.12.4 (Apple Git-37)