Slight documentation improvements

Author: iquito

README.md

@@ -3,13 +3,15 @@ Squirrel Validator Cascade
 
 [![Build Status](https://img.shields.io/travis/com/squirrelphp/validator-cascade.svg)](https://travis-ci.com/squirrelphp/validator-cascade) [![Test Coverage](https://api.codeclimate.com/v1/badges/e056be025c6db0eb31f1/test_coverage)](https://codeclimate.com/github/squirrelphp/validator-cascade/test_coverage) ![PHPStan](https://img.shields.io/badge/style-level%207-success.svg?style=flat-round&label=phpstan) [![Packagist Version](https://img.shields.io/packagist/v/squirrelphp/validator-cascade.svg?style=flat-round)](https://packagist.org/packages/squirrelphp/validator-cascade)  [![PHP Version](https://img.shields.io/packagist/php-v/squirrelphp/validator-cascade.svg)](https://packagist.org/packages/squirrelphp/validator-cascade) [![Software License](https://img.shields.io/badge/license-MIT-success.svg?style=flat-round)](LICENSE)
 
-Reimplements the `Valid` constraint in the Symfony Validator component as `Cascade` annotation which is more straightforward to use and has no surprising behavior.
+Reimplements the `Valid` constraint in the Symfony validator component as `Cascade` annotation which is more straightforward to use than `Valid` and has no surprising behavior.
+
+This component is compatible with the Symfony validator component starting from version 4.0 and will be adapted to support future versions of Symfony if necessary.
 
 Installation
 ------------
 
     composer require squirrelphp/validator-cascade
-
+    
 Table of contents
 -----------------
 
@@ -20,7 +22,7 @@ Table of contents
 Usage
 -----
 
-`Cascade` makes sure an object or an array of objects are validated, so it cascades validation.
+`Cascade` is a constraint validation which makes sure an object or an array of objects are validated by the Symfony validator component, so it cascades validation.
 
 There are only two options:
 
@@ -33,9 +35,9 @@ That is it!
 Example
 -------
 
-Belong is a common example in real applications: You might have an order and multiple possible addresses for the order (one for shipping, one for invoice) with different requirements, and some addresses should be optional, but if they are specified they should still be validated in full.
+Below is a common example in real applications: You might have an order and multiple possible addresses for the order (one for shipping, one for invoice) with different requirements, and some addresses should be optional, but if they are specified they should still be validated.
 
-`$shippingAddress` shows how to trigger specific validation groups in the child object, in this case to make the phone number a mandatory part of the information (often the case for shipping, but not necessarily for invoice or other address use) in addition to the "Default" constraints.
+`$shippingAddress` shows how to trigger specific validation groups in the child object, in this case to make the phone number a mandatory part of the information (often the case for shipping, but usually not necessary for other uses) in addition to the "Default" constraints.
 
 `$invoiceAddress` is only validated if the validation group "alternateInvoiceAddress" is passed to the validator (which could be done if the user selected an option like "choose different invoice address"). The phone number is optional, as we do not pass the `trigger` option so only the Default group is validated in the Adress object.
 
@@ -117,7 +119,8 @@ $order->invoiceAddress = new Address();
 // so only shippingAddress must be specified
 $symfonyValidator->validate($order);
 
-// This also validates the invoice address
+// This also validates the invoice address in addition
+// to the shipping address
 $symfonyValidator->validate($order, null, [
     "Default",
     "alternateInvoiceAddress",
@@ -154,12 +157,12 @@ This is fine for simple objects or when you don't need any validation groups at
 public $someobject;
 ```
 
-The `Valid` assertion above only triggers when you validate the "invoice" validation group, which is what you would expect. Yet there is plenty of other unexpected behavior:
+The `Valid` assertion above only triggers when you validate the "invoice" validation group, which is what you would expect. Yet there is plenty of unexpected behavior:
 
 - It only triggers the validation group "invoice" in $someobject, no other validation groups are passed to the object (if, for example, you are validating the groups "Default" and "invoice" the group "Default" never reaches $someobject, only "invoice")
 - There is no way to change which validation groups are triggered in $someobject
-- There is a "traverse" option for `Valid` which is not used when defining a validation group. Although the "traverse" option seems a bit exotic anyway, it is another behavior change
+- The "traverse" option for `Valid` is not used when a validation group is defined. Although the "traverse" option should probably not be used or needed in general
 
-Having validation groups both as a trigger and as a filter severly limits how you can use it, and makes most use cases (like our example with addresses) impossible to do with `Valid`. Even if you manage to make it work, your options will not be self explanatory and it is easy to make mistakes.
+Having validation groups both as a trigger and as a filter severly limits how you can use it, and makes most use cases (like our [example with addresses](#example)) impossible to do with `Valid`. Even if you manage to make it work, your code will not be self explanatory and it is easy to make mistakes or misunderstand the annotations.
 
-`Cascade` as defined in this component separates which validation group the constraint belongs to and which validation groups are triggered in the child object(s). What it cannot do is cascade the validation groups of the parent to the child object, as this information is only available in the `RecursiveContextualValidator` class of the validator component and cannot be accessed without changing a lot of the internals of the validator component.
+`Cascade` as defined in this component separates which validation group the constraint belongs to and which validation groups are triggered in the child object(s). What it cannot do is cascade the validation groups of the parent to the child object, as this information is only available in the `RecursiveContextualValidator` class of the validator component and cannot be accessed without changing a lot of the internals of the validator component (unfortunately).