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

* 'master' of github.com:yiisoft/yii2:
  Edited model.md up to Validation
  Just started editing

docs/guide/model.md

@@ -8,16 +8,15 @@ In keeping with the MVC approach, a model in Yii is intended for storing or temp
 - Massive attribute assignment: the ability to populate multiple model attributes in one step.
 - Scenario-based data validation.
 
-Models in Yii extend from the [[\yii\base\Model]] class. Models are typically used to both hold data and define the validation rules for that data. The validation rules greatly simply the generation of models from complex web forms.
+Models in Yii extend from the [[\yii\base\Model]] class. Models are typically used to both hold data and define the validation rules for that data (aka, the business logic). The business logic greatly simplifies the generation of models from complex web forms by providing validation and error reporting.
-The Model class is also the base for more advanced models with additional functionality such as [Active Record](active-record.md).
+The Model class is also the base class for more advanced models with additional functionality, such as [Active Record](active-record.md).
 
 Attributes
 ----------
 
-Attributes store the actual data represented by a model and can
+The actual data represented by a model is stored in the model's *attributes*. Model attributes can
-be accessed like object member variables. For example, a `Post` model
+be accessed like the member variables of any object. For example, a `Post` model
-may contain a `title` attribute and a `content` attribute which may be
+may contain a `title` attribute and a `content` attribute, accessible as follows:
-accessed as follows:
 
 ```php
 $post = new Post;
@@ -28,7 +27,7 @@ echo $post->content;
 ```
 
 Since [[\yii\base\Model|Model]] implements the [ArrayAccess](http://php.net/manual/en/class.arrayaccess.php) interface,
-you can also access the attributes like accessing array elements:
+you can also access the attributes as if they were array elements:
 
 ```php
 $post = new Post;
@@ -51,8 +50,8 @@ class LoginForm extends \yii\base\Model
 }
 ```
 
-Derived model classes may use different ways to declare attributes by overriding the [[\yii\base\Model::attributes()|attributes()]]
+Derived model classes may declare attributes in different ways, by overriding the [[\yii\base\Model::attributes()|attributes()]]
-method. For example, [[\yii\db\ActiveRecord]] defines attributes as the column names of the database table
+method. For example, [[\yii\db\ActiveRecord]] defines attributes using the column names of the database table
 that is associated with the class.
 
 
@@ -60,13 +59,11 @@ Attribute Labels
 ----------------
 
 Attribute labels are mainly used for display purpose. For example, given an attribute `firstName`, we can declare
-a label `First Name` which is more user-friendly and can be displayed to end users in places such as form labels,
+a label `First Name` that is more user-friendly when displayed to end users in places such as form labels and 
 error messages. Given an attribute name, you can obtain its label by calling [[\yii\base\Model::getAttributeLabel()]].
 
-To declare attribute labels, you should override the [[\yii\base\Model::attributeLabels()]] method and return
+To declare attribute labels, override the [[\yii\base\Model::attributeLabels()]] method. The overridden method returns a mapping of attribute names to attribute labels, as shown in the example below. If an attribute is not found
-a mapping from attribute names to attribute labels, like shown in the example below. If an attribute is not found
+in this mapping, its label will be generated using the [[\yii\base\Model::generateAttributeLabel()]] method. In many cases, [[\yii\base\Model::generateAttributeLabel()]] will generate reasonable labels (e.g. `username` to `Username`, `orderNumber` to `Order Number`).
-in this mapping, its label will be generated using the [[\yii\base\Model::generateAttributeLabel()]] method, which
-in many cases, will generate reasonable labels (e.g. `username` to `Username`, `orderNumber` to `Order Number`).
 
 ```php
 // LoginForm has two attributes: username and password
@@ -88,17 +85,19 @@ class LoginForm extends \yii\base\Model
 Scenarios
 ---------
 
-A model may be used in different scenarios. For example, a `User` model may be used to collect user login inputs,
+A model may be used in different *scenarios*. For example, a `User` model may be used to collect user login inputs,
-and it may also be used for user registration purpose. For this reason, each model has a property named `scenario`
+but it may also be used for user registration purposes. In the one scenario, every piece of data is required; in the other, only the username and password would be. 
-which stores the name of the scenario that the model is currently being used in. As we will explain in the next
+
-few sections, the concept of scenario is mainly used for data validation and massive attribute assignment.
+To easily implement the business logic for different scenarios, each model has a property named `scenario`
+that stores the name of the scenario that the model is currently being used in. As will be explained in the next
+few sections, the concept of scenarios is mainly used for data validation and massive attribute assignment.
 
 Associated with each scenario is a list of attributes that are *active* in that particular scenario. For example,
 in the `login` scenario, only the `username` and `password` attributes are active; while in the `register` scenario,
 additional attributes such as `email` are *active*.
 
-Possible scenarios should be listed in the `scenarios()` method which returns an array whose keys are the scenario
+Possible scenarios should be listed in the `scenarios()` method. This method returns an array whose keys are the scenario
-names and whose values are the corresponding active attribute lists. Below is an example:
+names and whose values are lists of attributes that should be active in that scenario:
 
 ```php
 class User extends \yii\db\ActiveRecord
@@ -113,14 +112,14 @@ class User extends \yii\db\ActiveRecord
 }
 ```
 
-Sometimes, we want to mark an attribute as not safe for massive assignment (but we still want it to be validated).
+Sometimes, we want to mark an attribute as not safe for massive assignment (but we still want the attribute to be validated).
-We may do so by prefixing an exclamation character to the attribute name when declaring it in `scenarios()`. For example,
+We may do so by prefixing an exclamation character to the attribute name when declaring it in `scenarios()`. For example:
 
 ```php
 ['username', 'password', '!secret']
 ```
 
-Active model scenario could be set using one of the following ways:
+Identifying the active model scenario can be done using one of the following approaches:
 
 ```php
 class EmployeeController extends \yii\web\Controller
@@ -143,8 +142,7 @@ class EmployeeController extends \yii\web\Controller
 }
 ```
 
-In the example above we are using [Active Record](active-record.md). For basic form models it's rarely needed to
+The example above presumes that the model is based upon [Active Record](active-record.md). For basic form models, scenarios are rarely needed, as the basic form model is normally tied directly to a single form.
-use scenarios since form model is typically used for a single form.
 
 Validation
 ----------

docs/guide/performance.md

@@ -1,7 +1,7 @@
 Performance Tuning
 ==================
 
-Application performance consists of two parts. First is the framework performance
+The performance of your web application is based upon two parts. First is the framework performance
 and the second is the application itself. Yii has a pretty low performance impact
 on your application out of the box and can be fine-tuned further for production
 environment. As for the application, we'll provide some of the best practices