Improved documentation

docs/custom_rule.md

@@ -56,5 +56,6 @@ $validator->add('key', 'MyApp\Validation\Rule\ThisOrThat', [
 ];);
 
 // or less verbose
+$validator->add('key', 'MyApp\Validation\Rule\ThisOrThat(this=c&that=d)');
 $validator->add('key', 'MyApp\Validation\Rule\ThisOrThat(c,d)');
 ```

docs/index.md

@@ -24,20 +24,29 @@ $validation = new \Sirius\Validation\Validator;
 
 // let's validate an invoice form
 $validator->add(array(
-    'date:Date' => 'required | date',
-	'client_id:Client' => 'required | clientexists', // clientexists is an app-specific rule
-	'notify_recipients[*]:Send invoice to' => 'email', // same rule for an array of items
+    // :Date specifies the label for the field. It will be used in the error messages
+    'order_date:Date' => 'required | date',
+    // `clientexists` is an app-specific rule
+	'client_id:Client' => 'required | clientexists', 
+	// apply the same rule for an array of items
+	'notify_recipients[*]:Send invoice to' => 'email',
+	// apply a rule to a specific item in the array 
 	'shipping_address[line_1]:Address' => 'required'
 	'shipping_address[city]:City' => 'required'
 	'shipping_address[state]:State' => 'required'
 	'shipping_address[country]:Country' => 'required',
 	'lines[*]price:Price' => [
-	    'requiredWith(item=lines[*]product_id', // the price is required only if a product was selected
-	    'MyApp\Validator\Rule\InvoiceItemPrice' // another app-specific rule, specified as a class
+	    // the price is required only if a product was selected
+	    'requiredWith(item=lines[*]product_id)',
+	    // another app-specific rule applied to the price, specified as a class 
+	    'MyApp\Validator\Rule\InvoiceItemPrice' 
 	];,
 	'lines[*]quantity:Quantity' => [
-	    'requiredWith(item=lines[*]product_id',
-	    ('invoice_item_quantity', 'The quantity is not valid']; // here we have a custom error message
+	    // the price is required only if a product was selected
+	    'requiredWith(item=lines[*]product_id)',
+	    // here we have a custom validation rule with no parameters AND a custom error message
+	    'quantity_in_stock()(The quantity is not valid)'
+	    ; 
 	)
 ));
 ```
@@ -56,7 +65,7 @@ This may seem counter-productive but remember that your forms' input fields may
 ```
 
 2. Because, If I am to do server side validation I can receive a JSON
-```javascript
+```json
 {
 	"errors": {
 		"recipients[0]": "Field must be a valid email",

docs/translate_messages.md

@@ -4,11 +4,10 @@ title: Translating the error messages
 
 # Translating the error messages
 
-There are a couple of ways to translate the error messages, each having it's pros and cons:
+There are a couple of ways to translate the error messages, each having its pros and cons:
 
 1. Postpone the translation until display
 2. Use a translatable error message class
-3. Use translated string for the message templates
 
 ### 1.Postpone the translation until display
 
@@ -34,15 +33,6 @@ class TranslatableErrorMessage extends Sirius\Validation\ErrorMessage {
 }
 
 // later when constructing your validators
-$validator = new Sirius\Validation\Validator(null, new TranslatableErrorMessage);
-```
-
-### 3.Use translated string for the message templates
-
-```php
-// in the validator
-$validator->add('title:' . __('Title'), 'maxlength', 'max=100', __('{label} must have less than {max} characters'));
-
-// or the rule factory
-$ruleFactoryInstance->setErrorMessages('maxlength', __('This field must have less than {max} characters'), __('{label} must have less than {max} characters'));
+$translator = new MyTranslator();
+$validator = new Sirius\Validation\Validator(null, new TranslatableErrorMessage($translator));
 ```