From 908f3997bde730e5a739d9049520c4e9141adcfd Mon Sep 17 00:00:00 2001
From: babruix <romanalexey@gmail.com>
Date: Wed, 13 Mar 2013 01:46:34 +0100
Subject: [PATCH] Issue #1879396 by xjm: Added inline documentation to
 BlockBase::validate() and BlockBase::submit().

---
 core/modules/block/lib/Drupal/block/BlockBase.php | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/core/modules/block/lib/Drupal/block/BlockBase.php b/core/modules/block/lib/Drupal/block/BlockBase.php
index 9c90a5a..dda2af3 100644
--- a/core/modules/block/lib/Drupal/block/BlockBase.php
+++ b/core/modules/block/lib/Drupal/block/BlockBase.php
@@ -417,19 +417,28 @@ 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 validate($form, &$form_state) {
+
+    // If editing of machine name was disabled.
     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']);
+
+    // For new blocks only.
     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 +466,15 @@ 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.
       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)