Merge branch 'master' of git://github.com/yiisoft/yii2

framework/widgets/Block.php

@@ -10,6 +10,29 @@ namespace yii\widgets;
 use yii\base\Widget;
 
 /**
+ * Block records all output between [[begin()]] and [[end()]] calls and stores it in [[\yii\base\View::$blocks]].
+ * for later use.
+ *
+ * [[\yii\base\View]] component contains two methods [[\yii\base\View::beginBlock()]] and [[\yii\base\View::endBlock()]].
+ * The general idea is that you're defining block default in a view or layout:
+ *
+ * ```php
+ * <?php $this->beginBlock('messages', true) ?>
+ * Nothing.
+ * <?php $this->endBlock() ?>
+ * ```
+ *
+ * And then overriding default in sub-views:
+ *
+ * ```php
+ * <?php $this->beginBlock('username') ?>
+ * Umm... hello?
+ * <?php $this->endBlock() ?>
+ * ```
+ *
+ * Second parameter defines if block content should be outputted which is desired when rendering its content but isn't
+ * desired when redefining it in subviews.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */