massive improvement on class documentation

- added example code for application components
- added missing short description

[ci skip]

framework/yii/base/ActionFilter.php

@@ -8,6 +8,11 @@
 namespace yii\base;
 
 /**
+ * ActionFilter provides a base implementation for action filters that can be added to a controller
+ * to handle the `beforeAction` event.
+ *
+ * Check implementation of [[AccessControl]], [[PageCache]] and [[HttpCache]] as examples on how to use it.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/base/Component.php

@@ -10,6 +10,8 @@ namespace yii\base;
 use Yii;
 
 /**
+ * Component is the base class that implements the *property*, *event* and *behavior* features.
+ *
  * @include @yii/base/Component.md
  *
  * @property Behavior[] $behaviors List of behaviors attached to this component. This property is read-only.

framework/yii/base/ErrorHandler.php

@@ -16,6 +16,9 @@ use yii\web\HttpException;
  * ErrorHandler displays these errors using appropriate views based on the
  * nature of the errors and the mode the application runs at.
  *
+ * ErrorHandler is configured as an application component in [[yii\base\Application]] by default.
+ * You can access that instance via `Yii::$app->errorHandler`.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @author Timur Ruziev <resurtm@gmail.com>
  * @since 2.0

framework/yii/base/Formatter.php

@@ -19,6 +19,9 @@ use yii\helpers\Html;
  * The behavior of some of them may be configured via the properties of Formatter. For example,
  * by configuring [[dateFormat]], one may control how [[asDate()]] formats the value into a date string.
  *
+ * Formatter is configured as an application component in [[yii\base\Application]] by default.
+ * You can access that instance via `Yii::$app->formatter`.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/base/Model.php

@@ -46,7 +46,8 @@ use yii\validators\Validator;
  * @property ArrayIterator $iterator An iterator for traversing the items in the list. This property is
  * read-only.
  * @property string $scenario The scenario that this model is in. Defaults to [[DEFAULT_SCENARIO]].
- * @property ArrayObject $validators All the validators declared in the model. This property is read-only.
+ * @property ArrayObject|\yii\validators\Validator[] $validators All the validators declared in the model.
+ * This property is read-only.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0

framework/yii/base/Object.php

@@ -10,7 +10,10 @@ namespace yii\base;
 use Yii;
 
 /**
+ * Object is the base class that implements the *property* feature.
+ *
  * @include @yii/base/Object.md
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/base/Request.php

@@ -8,6 +8,7 @@
 namespace yii\base;
 
 /**
+ * Request represents a request that is handled by an [[Application]].
  *
  * @property boolean $isConsoleRequest The value indicating whether the current request is made via console.
  * @property string $scriptFile Entry script file path (processed w/ realpath()).

framework/yii/base/Response.php

@@ -8,6 +8,8 @@
 namespace yii\base;
 
 /**
+ * Response represents the response of an [[Application]] to a [[Request]].
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/base/ViewEvent.php

@@ -8,6 +8,8 @@
 namespace yii\base;
 
 /**
+ * ViewEvent represents events triggered by the [[View]] component.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/captcha/CaptchaAsset.php

@@ -10,6 +10,8 @@ namespace yii\captcha;
 use yii\web\AssetBundle;
 
 /**
+ * This asset bundle provides the javascript files needed for the [[Captcha]] widget.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/console/Request.php

@@ -8,6 +8,10 @@
 namespace yii\console;
 
 /**
+ * The console Request represents the environment information for a console application.
+ *
+ * It is a wrapper for the PHP `$_SERVER` variable which holds information about the
+ * currently running PHP script and the command line arguments given to it.
  *
  * @property array $params The command line arguments. It does not include the entry script name.
  *

framework/yii/console/Response.php

@@ -8,6 +8,8 @@
 namespace yii\console;
 
 /**
+ * The console Response represents the result of a console application by holding the [[exitCode]].
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/grid/ActionColumn.php

@@ -12,6 +12,8 @@ use Closure;
 use yii\helpers\Html;
 
 /**
+ * ActionColumn is a column for the [[GridView]] widget that displays buttons for viewing and manipulating the items.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/grid/DataColumn.php

@@ -15,6 +15,10 @@ use yii\helpers\Html;
 use yii\helpers\Inflector;
 
 /**
+ * DataColumn is the default column type for the [[GridView]] widget.
+ *
+ * It is used to show data columns and allows sorting them.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/grid/GridView.php

@@ -16,6 +16,10 @@ use yii\helpers\Json;
 use yii\widgets\BaseListView;
 
 /**
+ * The GridView widget is used to display data in a grid.
+ *
+ * It provides features like sorting, paging and also filtering the data.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/grid/GridViewAsset.php

@@ -10,6 +10,7 @@ namespace yii\grid;
 use yii\web\AssetBundle;
 
 /**
+ * This asset bundle provides the javascript files for the [[GridView]] widget.
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0

framework/yii/i18n/Formatter.php

@@ -19,6 +19,15 @@ use yii\base\InvalidConfigException;
  * Formatter requires the PHP "intl" extension to be installed. Formatter supports localized
  * formatting of date, time and numbers, based on the current [[locale]].
  *
+ * This Formatter can replace the `formatter` application component that is configured by default.
+ * To do so, add the following to your application config under `components`:
+ *
+ * ```php
+ * 'formatter' => [
+ *     'class' => 'yii\i18n\Formatter',
+ * ]
+ * ```
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/i18n/I18N.php

@@ -14,6 +14,9 @@ use yii\base\InvalidConfigException;
 /**
  * I18N provides features related with internationalization (I18N) and localization (L10N).
  *
+ * I18N is configured as an application component in [[yii\base\Application]] by default.
+ * You can access that instance via `Yii::$app->i18n`.
+ *
  * @property MessageFormatter $messageFormatter The message formatter to be used to format message via ICU
  * message format. Note that the type of this property differs in getter and setter. See
  * [[getMessageFormatter()]] and [[setMessageFormatter()]] for details.

framework/yii/validators/PunycodeAsset.php

@@ -9,6 +9,8 @@ namespace yii\validators;
 use yii\web\AssetBundle;
 
 /**
+ * This asset bundle provides the javascript files needed for the [[EmailValidator]]s client validation.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/validators/ValidationAsset.php

@@ -9,6 +9,8 @@ namespace yii\validators;
 use yii\web\AssetBundle;
 
 /**
+ * This asset bundle provides the javascript files for client validation.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/web/AssetConverter.php

@@ -14,6 +14,8 @@ use yii\base\Exception;
 /**
  * AssetConverter supports conversion of several popular script formats into JS or CSS scripts.
  *
+ * It is used by [[AssetManager]] to convert files after they have been published.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
@@ -63,6 +65,8 @@ class AssetConverter extends Component implements AssetConverterInterface
 	 * @param string $asset the name of the asset file
 	 * @param string $result the name of the file to be generated by the converter command
 	 * @return bool true on success, false on failure. Failures will be logged.
+	 * @throws \yii\base\Exception when the command fails and YII_DEBUG is true.
+	 * In production mode the error will be logged.
 	 */
 	protected function runCommand($command, $basePath, $asset, $result)
 	{

framework/yii/web/AssetManager.php

@@ -16,6 +16,22 @@ use yii\helpers\FileHelper;
 /**
  * AssetManager manages asset bundles and asset publishing.
  *
+ * AssetManager is configured as an application component in [[yii\web\Application]] by default.
+ * You can access that instance via `Yii::$app->assetManager`.
+ *
+ * You can modify its configuration by adding an array to your application config under `components`
+ * as it is shown in the following example:
+ *
+ * ~~~
+ * 'assetManager' => [
+ *     'bundles' => [
+ *         // you can override AssetBundle configs here
+ *     ],
+ *     //'linkAssets' => true,
+ *     // ...
+ * ]
+ * ~~~
+ *
  * @property AssetConverterInterface $converter The asset converter. Note that the type of this property
  * differs in getter and setter. See [[getConverter()]] and [[setConverter()]] for details.
  *

framework/yii/web/CacheSession.php

@@ -19,7 +19,17 @@ use yii\base\InvalidConfigException;
  *
  * Beware, by definition cache storage are volatile, which means the data stored on them
  * may be swapped out and get lost. Therefore, you must make sure the cache used by this component
- * is NOT volatile. If you want to use database as storage medium, use [[DbSession]] is a better choice.
+ * is NOT volatile. If you want to use database as storage medium, [[DbSession]] is a better choice.
+ *
+ * The following example shows how you can configure the application to use CacheSession:
+ * Add the following to your application config under `components`:
+ *
+ * ~~~
+ * 'session' => [
+ *     'class' => 'yii\web\CacheSession',
+ *     // 'cache' => 'mycache',
+ * ]
+ * ~~~
  *
  * @property boolean $useCustomStorage Whether to use custom storage. This property is read-only.
  *

framework/yii/web/Controller.php

@@ -150,6 +150,13 @@ class Controller extends \yii\base\Controller
 	 * Redirects the browser to the specified URL.
 	 * This method is a shortcut to [[Response::redirect()]].
 	 *
+	 * You can use it in an action by returning the [[Response]] directly:
+	 *
+	 * ```php
+	 * // stop executing this action and redirect to login page
+	 * return $this->redirect(['login']);
+	 * ```
+	 *
 	 * @param string|array $url the URL to be redirected to. This can be in one of the following formats:
 	 *
 	 * - a string representing a URL (e.g. "http://example.com")
@@ -172,6 +179,14 @@ class Controller extends \yii\base\Controller
 
 	/**
 	 * Redirects the browser to the home page.
+	 *
+	 * You can use this method in an action by returning the [[Response]] directly:
+	 *
+	 * ```php
+	 * // stop executing this action and redirect to home page
+	 * return $this->goHome();
+	 * ```
+	 *
 	 * @return Response the current response object
 	 */
 	public function goHome()
@@ -181,6 +196,14 @@ class Controller extends \yii\base\Controller
 
 	/**
 	 * Redirects the browser to the last visited page.
+	 *
+	 * You can use this method in an action by returning the [[Response]] directly:
+	 *
+	 * ```php
+	 * // stop executing this action and redirect to last visited page
+	 * return $this->goBack();
+	 * ```
+	 *
 	 * @param string|array $defaultUrl the default return URL in case it was not set previously.
 	 * If this is null and the return URL was not set previously, [[Application::homeUrl]] will be redirected to.
 	 * Please refer to [[User::setReturnUrl()]] on accepted format of the URL.
@@ -195,6 +218,14 @@ class Controller extends \yii\base\Controller
 	/**
 	 * Refreshes the current page.
 	 * This method is a shortcut to [[Response::refresh()]].
+	 *
+	 * You can use it in an action by returning the [[Response]] directly:
+	 *
+	 * ```php
+	 * // stop executing this action and refresh the current page
+	 * return $this->refresh();
+	 * ```
+	 *
 	 * @param string $anchor the anchor that should be appended to the redirection URL.
 	 * Defaults to empty. Make sure the anchor starts with '#' if you want to specify it.
 	 * @return Response the response object itself

framework/yii/web/DbSession.php

@@ -19,6 +19,7 @@ use yii\base\InvalidConfigException;
  * must be pre-created. The table name can be changed by setting [[sessionTable]].
  *
  * The following example shows how you can configure the application to use DbSession:
+ * Add the following to your application config under `components`:
  *
  * ~~~
  * 'session' => [

framework/yii/web/HttpCache.php

@@ -12,7 +12,32 @@ use yii\base\ActionFilter;
 use yii\base\Action;
 
 /**
- * The HttpCache provides functionality for caching via HTTP Last-Modified and Etag headers
+ * The HttpCache provides functionality for caching via HTTP Last-Modified and Etag headers.
+ *
+ * It is an action filter that can be added to a controller and handles the `beforeAction` event.
+ *
+ * To use AccessControl, declare it in the `behaviors()` method of your controller class.
+ * In the following example the filter will be applied to the `list`-action and
+ * the Last-Modified header will contain the date of the last update to the user table in the database.
+ *
+ * ~~~
+ * public function behaviors()
+ * {
+ *     return [
+ *         'httpCache' => [
+ *             'class' => \yii\web\HttpCache::className(),
+ *             'only' => ['list'],
+ *             'lastModified' => function ($action, $params) {
+ *                 $q = new Query();
+ *                 return strtotime($q->from('users')->max('updated_timestamp'));
+ *             },
+ * //            'etagSeed' => function ($action, $params) {
+ * //                return // generate etag seed here
+ * //            }
+ *         ],
+ *     ];
+ * }
+ * ~~~
  *
  * @author Da:Sourcerer <webmaster@dasourcerer.net>
  * @author Qiang Xue <qiang.xue@gmail.com>

framework/yii/web/HttpException.php

@@ -16,6 +16,14 @@ use yii\base\UserException;
  * keeps a standard HTTP status code (e.g. 404, 500). Error handlers may use this status code
  * to decide how to format the error page.
  *
+ * Throwing an HttpException like in the following example will result in the 404 page to be displayed.
+ *
+ * ```php
+ * if ($item === null) { // item does not exist
+ *     throw new \yii\web\HttpException(404, 'The requested Item could not be found.');
+ * }
+ * ```
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/web/PageCache.php

@@ -15,6 +15,35 @@ use yii\caching\Dependency;
 /**
  * The PageCache provides functionality for whole page caching
  *
+ * It is an action filter that can be added to a controller and handles the `beforeAction` event.
+ *
+ * To use PageCache, declare it in the `behaviors()` method of your controller class.
+ * In the following example the filter will be applied to the `list`-action and
+ * cache the whole page for maximum 60 seconds or until the count of entries in the post table changes.
+ * It also stores different versions of the page depended on the route ([[varyByRoute]] is true by default),
+ * the application language and user id.
+ *
+ * ~~~
+ * public function behaviors()
+ * {
+ *     return [
+ *         'pageCache' => [
+ *             'class' => \yii\web\PageCache::className(),
+ *             'only' => ['list'],
+ *             'duration' => 60,
+ *             'dependecy' => [
+ *                 'class' => 'yii\caching\DbDependency',
+ *                 'sql' => 'SELECT COUNT(*) FROM post',
+ *             ],
+ *             'variations' => [
+ *                 Yii::$app->language,
+ *                 Yii::$app->user->id
+ *             ]
+ *         ],
+ *     ];
+ * }
+ * ~~~
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */
@@ -60,6 +89,7 @@ class PageCache extends ActionFilter
 	 * [
 	 *     Yii::$app->language,
 	 * ]
+	 * ~~~
 	 */
 	public $variations;
 	/**

framework/yii/web/Request.php

@@ -18,6 +18,9 @@ use yii\helpers\Security;
  * Also it provides an interface to retrieve request parameters from $_POST, $_GET, $_COOKIES and REST
  * parameters sent via other HTTP methods like PUT or DELETE.
  *
+ * Request is configured as an application component in [[yii\web\Application]] by default.
+ * You can access that instance via `Yii::$app->request`.
+ *
  * @property string $absoluteUrl The currently requested absolute URL. This property is read-only.
  * @property string $acceptTypes User browser accept types, null if not present. This property is read-only.
  * @property array $acceptedContentTypes The content types ordered by the preference level. The first element

framework/yii/web/Response.php

@@ -22,6 +22,20 @@ use yii\helpers\StringHelper;
  * It holds the [[headers]], [[cookies]] and [[content]] that is to be sent to the client.
  * It also controls the HTTP [[statusCode|status code]].
  *
+ * Response is configured as an application component in [[yii\web\Application]] by default.
+ * You can access that instance via `Yii::$app->response`.
+ *
+ * You can modify its configuration by adding an array to your application config under `components`
+ * as it is shown in the following example:
+ *
+ * ~~~
+ * 'response' => [
+ *     'format' => yii\web\Response::FORMAT_JSON,
+ *     'charset' => 'UTF-8',
+ *     // ...
+ * ]
+ * ~~~
+ *
  * @property CookieCollection $cookies The cookie collection. This property is read-only.
  * @property HeaderCollection $headers The header collection. This property is read-only.
  * @property boolean $isClientError Whether this response indicates a client error. This property is

framework/yii/web/Session.php

@@ -15,7 +15,7 @@ use yii\base\InvalidParamException;
  * Session provides session data management and the related configurations.
  *
  * Session is a Web application component that can be accessed via `Yii::$app->session`.
-
+ *
  * To start the session, call [[open()]]; To complete and send out session data, call [[close()]];
  * To destroy the session, call [[destroy()]].
  *

framework/yii/web/UrlManager.php

@@ -14,6 +14,22 @@ use yii\caching\Cache;
 /**
  * UrlManager handles HTTP request parsing and creation of URLs based on a set of rules.
  *
+ * UrlManager is configured as an application component in [[yii\base\Application]] by default.
+ * You can access that instance via `Yii::$app->urlManager`.
+ *
+ * You can modify its configuration by adding an array to your application config under `components`
+ * as it is shown in the following example:
+ *
+ * ~~~
+ * 'urlManager' => [
+ *     'enablePrettyUrl' => true,
+ *     'rules' => [
+ *         // your rules go here
+ *     ],
+ *     // ...
+ * ]
+ * ~~~
+ *
  * @property string $baseUrl The base URL that is used by [[createUrl()]] to prepend URLs it creates.
  * @property string $hostInfo The host info (e.g. "http://www.example.com") that is used by
  * [[createAbsoluteUrl()]] to prepend URLs it creates.

framework/yii/web/UrlRule.php

@@ -11,7 +11,17 @@ use yii\base\Object;
 use yii\base\InvalidConfigException;
 
 /**
- * UrlRule represents a rule used for parsing and generating URLs.
+ * UrlRule represents a rule used by [[UrlManager]] for parsing and generating URLs.
+ *
+ * To define your own URL parsing and creation logic you can extend from this class
+ * and add it to [[UrlManager::rules]] like this:
+ *
+ * ~~~
+ * 'rules' => [
+ *     ['class' => 'MyUrlRule', 'pattern' => '...', 'route' => 'site/index', ...],
+ *     // ...
+ * ]
+ * ~~~
  *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0

framework/yii/web/User.php

@@ -20,6 +20,21 @@ use yii\base\InvalidConfigException;
  * User works with a class implementing the [[IdentityInterface]]. This class implements
  * the actual user authentication logic and is often backed by a user database table.
  *
+ * User is configured as an application component in [[yii\web\Application]] by default.
+ * You can access that instance via `Yii::$app->user`.
+ *
+ * You can modify its configuration by adding an array to your application config under `components`
+ * as it is shown in the following example:
+ *
+ * ~~~
+ * 'user' => [
+ *     'identityClass' => 'app\models\User', // User must implement the IdentityInterface
+ *     'enableAutoLogin' => true,
+ *     // 'loginUrl' => ['user/login'],
+ *     // ...
+ * ]
+ * ~~~
+ *
  * @property string|integer $id The unique identifier for the user. If null, it means the user is a guest.
  * This property is read-only.
  * @property IdentityInterface $identity The identity object associated with the currently logged user. Null

framework/yii/web/View.php

@@ -22,6 +22,22 @@ use yii\base\InvalidConfigException;
  *
  * View provides a set of methods (e.g. [[render()]]) for rendering purpose.
  *
+ * View is configured as an application component in [[yii\base\Application]] by default.
+ * You can access that instance via `Yii::$app->view`.
+ *
+ * You can modify its configuration by adding an array to your application config under `components`
+ * as it is shown in the following example:
+ *
+ * ~~~
+ * 'view' => [
+ *     'theme' => 'app\themes\MyTheme',
+ *     'renderers' => [
+ *         // you may add Smarty or Twig renderer here
+ *     ]
+ *     // ...
+ * ]
+ * ~~~
+ *
  * @property \yii\web\AssetManager $assetManager The asset manager. Defaults to the "assetManager" application
  * component.
  *

framework/yii/web/XmlResponseFormatter.php

@@ -17,6 +17,8 @@ use yii\helpers\StringHelper;
 /**
  * XmlResponseFormatter formats the given data into an XML response content.
  *
+ * It is used by [[Response]] to format response data.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */

framework/yii/web/YiiAsset.php

@@ -8,6 +8,8 @@
 namespace yii\web;
 
 /**
+ * This asset bundle provides the base javascript files for the Yii Framework.
+ *
  * @author Qiang Xue <qiang.xue@gmail.com>
  * @since 2.0
  */