Streamline validators.md index

Makes it so the index looks more like a cheatsheet, condensing
information instead of making long lists that require lots of
scrolling to explore.

Additionally, the happy path for each validator was also
added, providing a quick reference use for comparison.

The direct markdown links were replaced by titled markdown
references, offering mouse-over tooltips over links that
display the validator one-line description.

To ensure a proper source of truth for these new index
goodies, the AssertionMessageLinter was modified to
verify that the first assertion in each doc is a
single-line validator that passes (a happy path), further
making our documentation conventions more solid.

Author: alganet

docs/validators.md

@@ -14,12 +14,12 @@ Alphanumeric is a combination of alphabetic (a-z and A-Z) and numeric (0-9)
 characters.
 
 ```php
-v::alnum()->assert('foo 123');
-// → "foo 123" must contain only letters (a-z) and digits (0-9)
-
 v::alnum(' ')->assert('foo 123');
 // Validation passes successfully
 
+v::alnum()->assert('foo 123');
+// → "foo 123" must contain only letters (a-z) and digits (0-9)
+
 v::alnum()->assert('100%');
 // → "100%" must contain only letters (a-z) and digits (0-9)
 

docs/validators/Alnum.md

@@ -12,12 +12,12 @@ Validates whether the input contains only alphabetic characters. This is similar
 to [Alnum](Alnum.md), but it does not allow numbers.
 
 ```php
-v::alpha()->assert('some name');
-// → "some name" must contain only letters (a-z)
-
 v::alpha(' ')->assert('some name');
 // Validation passes successfully
 
+v::alpha()->assert('some name');
+// → "some name" must contain only letters (a-z)
+
 v::alpha()->assert('Cedric-Fabian');
 // → "Cedric-Fabian" must contain only letters (a-z)
 

docs/validators/Alpha.md

@@ -10,6 +10,9 @@ SPDX-License-Identifier: MIT
 Validates any input as invalid.
 
 ```php
+v::not(v::alwaysInvalid())->assert('whatever');
+// Validation passes successfully
+
 v::alwaysInvalid()->assert('whatever');
 // → "whatever" must be valid
 ```

docs/validators/AlwaysInvalid.md

@@ -10,12 +10,12 @@ SPDX-License-Identifier: MIT
 Validates whether the input is between two other values, exclusively.
 
 ```php
-v::betweenExclusive(10, 20)->assert(10);
-// → 10 must be greater than 10 and less than 20
-
 v::betweenExclusive('a', 'e')->assert('c');
 // Validation passes successfully
 
+v::betweenExclusive(10, 20)->assert(10);
+// → 10 must be greater than 10 and less than 20
+
 v::betweenExclusive(new DateTime('yesterday'), new DateTime('tomorrow'))->assert(new DateTime('today'));
 // Validation passes successfully
 

docs/validators/BetweenExclusive.md

@@ -9,6 +9,11 @@ SPDX-License-Identifier: MIT
 
 Validates the return of a [callable][] for a given input.
 
+```php
+v::call(str_split(...), v::arrayType()->lengthEquals(5))->assert('world');
+// Validation passes successfully
+```
+
 Consider the following variable:
 
 ```php

docs/validators/Call.md

@@ -11,9 +11,7 @@ SPDX-License-Identifier: MIT
 Validates the input using the return of a given callable.
 
 ```php
-v::callback(
-    fn (int $input): bool => $input + ($input / 2) == 15,
-)->assert(10);
+v::callback(fn (int $input): bool => $input % 5 === 0,)->assert(10);
 // Validation passes successfully
 ```
 

docs/validators/Callback.md

@@ -11,12 +11,12 @@ SPDX-License-Identifier: MIT
 Validates if a string is in a specific charset.
 
 ```php
-v::charset('ASCII')->assert('açúcar');
-// → "açúcar" must only contain characters from the `["ASCII"]` charset
-
 v::charset('ASCII')->assert('sugar');
 // Validation passes successfully
 
+v::charset('ASCII')->assert('açúcar');
+// → "açúcar" must only contain characters from the `["ASCII"]` charset
+
 v::charset('ISO-8859-1', 'EUC-JP')->assert('日本国');
 // Validation passes successfully
 ```

docs/validators/Charset.md

@@ -10,6 +10,11 @@ SPDX-License-Identifier: MIT
 
 Validates the input against a series of validators until the first fails.
 
+```php
+v::circuit(v::intVal(), v::floatVal())->assert(15);
+// Validation passes successfully
+```
+
 This validator can be handy for getting the least error messages possible from a chain.
 
 This validator can be helpful in combinations with [Lazy](Lazy.md). An excellent example is when you want to validate a

docs/validators/Circuit.md

@@ -10,6 +10,11 @@ SPDX-License-Identifier: MIT
 Validates if the input is a Brazilian National Registry of Legal Entities (CNPJ) number.
 Ignores non-digit chars, so use `->digit()` if needed.
 
+```php
+v::cnpj()->assert('00394460005887');
+// Validation passes successfully
+```
+
 ## Templates
 
 ### `Cnpj::TEMPLATE_STANDARD`