From 38019610c2ed1468b3db5317b5c2969c57f1051f Mon Sep 17 00:00:00 2001
From: babruix <romanalexey@gmail.com>
Date: Mon, 18 Mar 2013 20:26:00 +0100
Subject: [PATCH]  #1879396 by xjm: Added inline documentation to
 BlockBase::validate() and BlockBase::submit().

---
 core/modules/block/lib/Drupal/block/BlockBase.php | 17 ++++++++++++-----
 1 file changed, 12 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..bf1a224 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -413,23 +413,29 @@ public function blockForm($form, &$form_state) {
 
   /**
    * Implements \Drupal\block\BlockInterface::validate().
-   *
+   * Before send block to validation function BlockBase::blockValdiate(),
+   * need some preparation of $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.
    * 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 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 +463,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 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)