chore: updated usage, methods and custom exception messages sections

Author: andrepimpao

docs/02-usage.md

@@ -3,12 +3,22 @@
 - Usage
   - Fluent
   - Dependency Injection
-- Validation
+- Methods
   - assert
   - validate
+  - getRules
+  - addRule
+- Exception Handling
+- Custom Exception Messages
 
 ## Usage
 
+This library allows you to use validate data in two different ways:
+- In a fluent way, making use of magic methods. The goal is to be able to create a set of rules with minimum setup;
+- In a traditional way, making use of dependency injection. You may not like the fluent approach, and prefer to work this way.
+
+Both should work exactly the same.
+
 ### Fluent
 
 ```php
@@ -40,18 +50,116 @@ use ProgrammatorDev\YetAnotherPhpValidator\Validator;
  */
 function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem): float
 {
-    (new Validator(new Rule\Range(-90, 90)))
-        ->assert($latitude, 'Latitude');
-    (new Validator(new Rule\Range(-180, 180)))
-        ->assert($longitude, 'Longitude');
-    (new Validator(new Rule\NotBlank(), new Rule\Choice(['METRIC', 'IMPERIAL'])))
-        ->assert($unitSystem, 'Unit System');
+    (new Validator(new Rule\Range(-90, 90)))->assert($latitude, 'Latitude');
+    (new Validator(new Rule\Range(-180, 180)))->assert($longitude, 'Longitude');
+    (new Validator(new Rule\NotBlank(), new Rule\Choice(['METRIC', 'IMPERIAL'])))->assert($unitSystem, 'Unit System');
 
     // ...
 }
 ```
 
-A `addRule` method is also available that may be useful for conditional rules:
+## Methods
+
+### `assert`
+
+This method throws a `ValidationException` when the first rule fails, otherwise nothing is returned.
+
+```php
+/**
+ * @throws ValidationException
+ */
+assert(mixed $value, string $name): void;
+```
+
+An example on how to handle an exception:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem): float
+{
+    Validator::range(-90, 90)->assert($latitude, 'Latitude');
+    Validator::range(-180, 180)->assert($longitude, 'Longitude');
+    Validator::notBlank()->choice(['METRIC', 'IMPERIAL'])->assert($unitSystem, 'Unit System');
+    
+    // ...
+}
+
+try {
+    getWeatherTemperature(latitude: 100, longitude: 50, unitSystem: 'METRIC');
+}
+catch (ValidationException $exception) {
+    echo $exception->getMessage(); // The "Latitude" value should be between "-90" and "90", "100" given.
+}
+```
+
+> **Note**
+> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> Check the [Usage](#usage) section for more information.
+
+### `validate`
+
+This method always returns a `bool` when a rule fails, useful for conditions.
+
+```php
+validate(mixed $value): bool
+```
+
+An example:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+if (!Validator::range(-90, 90)->validate($latitude)) {
+    // Do something...
+} 
+```
+
+> **Note**
+> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> Check the [Usage](#usage) section for more information.
+
+### `getRules`
+
+Returns an array with the defined set of rules.
+
+```php
+/**
+ * @returns RuleInterface[] 
+ */
+getRules(): array
+```
+
+An example:
+
+```php
+use ProgrammatorDev\YetAnotherPhpValidator\Rule;
+use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+
+$validator = new Validator(new Rule\GreaterThanOrEqual(0), new Rule\LessThanOrEqual(100));
+
+print_r($validator->getRules());
+
+// Array ( 
+//    [0] => ProgrammatorDev\YetAnotherPhpValidator\Rule\GreaterThanOrEqual Object 
+//    [1] => ProgrammatorDev\YetAnotherPhpValidator\Rule\LessThanOrEqual Object
+// ) 
+```
+
+> **Note**
+> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same.
+> Check the [Usage](#usage) section for more information.
+
+### `addRule`
+
+Adds a rule to a set of rules. May be useful for conditional validations.
+
+```php
+addRule(RuleInterface $rule): self
+```
+
+An example:
 
 ```php
 use ProgrammatorDev\YetAnotherPhpValidator\Rule;
@@ -71,30 +179,29 @@ function calculateDiscount(float $price, float $discount, string $type): float
 }
 ```
 
-## Validation
+> **Note**
+> The example only shows one usage approach, but both Fluent and Dependency Injection usage approaches should work the same. 
+> Check the [Usage](#usage) section for more information.
 
-### `assert`
+## Exception Handling
 
-```php
-use ProgrammatorDev\YetAnotherPhpValidator\Exception\ValidationException;
-use ProgrammatorDev\YetAnotherPhpValidator\Validator;
+## Custom Exception Messages
 
-// function getWeatherTemperature(float $latitude, float $longitude, string $unitSystem)
+All rules have at least one error message that can be customized (some rules have more than one error message for different case scenarios).
 
-try {
-    getWeatherTemperature(100, 50, 'METRIC');
-}
-catch (ValidationException $exception) {
-    echo $exception->getMessage(); // The "Latitude" value should be between "-90" and "90", "100" given.
-}
-```
+Every message has a list of dynamic parameters to help create an intuitive error text (like the invalid value, constraints, names, and others).
+To check what parameters and messages are available, look into the Options section in the page of the rule you are looking for. 
+Go to [Rules](03-rules.md) to see all available rules.
 
-### `validate`
+The following example uses the [Choice](03x-rules-choice.md) rule with a custom error message:
 
 ```php
 use ProgrammatorDev\YetAnotherPhpValidator\Validator;
 
-if (!Validator::range(-90, 90)->validate($latitude)) {
-    // do something...
-} 
+Validator::choice(
+    constraints: ['red', 'green', 'blue'],
+    message: '"{{ value }}" is not a valid {{ name }}! You must select one of {{ constraints }}.'
+)->assert('yellow', 'color');
+
+// "yellow" is not a valid color! You must select one of [red, green, blue].
 ```