Update transform validators documentation

Adds an example on how to use transform validator objects and clarifies
the usage of the return type of the base function.

book/chapters/validators.md

@@ -5,20 +5,36 @@ There are two forms of validators:
 * `transform` validators: mutating
 * `check` validators: non-mutating (recommended unless the parsed string must be mutated)
 
-A transform validator comes in one form, a function with the signature `std::string(std::string)`.
-The function will take a string and return the modified version of the string. If there is an error,
-the function should throw a `CLI::ValidationError` with the appropriate reason as a message.
+A transform validator comes in one form, a function with the signature `std::string(std::string&)`. The function will
+take a string and return an error message, or an empty string if input is valid. If there is an error, the function
+should throw a `CLI::ValidationError` with the appropriate reason as a message.
 
-However, `check` validators come in two forms; either a simple function with the const version of the
-above signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This
-structure has two members that a user should set; one (`func_`) is the function to add to the Option
+An example of a mutating validator:
+
+```cpp
+auto transform_validator = CLI::Validator(
+        [](std::string &input) {
+            if (input == "error") {
+                return "error is not a valid value";
+            } else if (input == "unexpected") {
+                throw CLI::ValidationError{"Unexpected error"};
+            }
+            input = "new string";
+            return "";
+        }, "VALIDATOR DESCRIPTION", "Validator name");
+
+cli_global.add_option("option")->transform(transform_validator);
+```
+
+However, `check` validators come in two forms; either a simple function with the const version of the above
+signature, `std::string(const std::string &)`, or a subclass of `struct CLI::Validator`. This structure has two members
+that a user should set; one (`func_`) is the function to add to the Option
 (exactly matching the above function signature, since it will become that function), and the other is
-`name_`, and is the type name to set on the Option (unless empty, in which case the typename will be
-left unchanged).
+`name_`, and is the type name to set on the Option (unless empty, in which case the typename will be left unchanged).
 
-Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them
-as if they were a function. In CLI11, const static versions of the validators are provided so that
-the user does not have to call a constructor also.
+Validators can be combined with `&` and `|`, and they have an `operator()` so that you can call them as if they were a
+function. In CLI11, const static versions of the validators are provided so that the user does not have to call a
+constructor also.
 
 An example of a custom validator:
 
@@ -37,7 +53,8 @@ struct LowerCaseValidator : public Validator {
 const static LowerCaseValidator Lowercase;
 ```
 
-If you were not interested in the extra features of Validator, you could simply pass the lambda function above to the `->check()` method of `Option`.
+If you were not interested in the extra features of Validator, you could simply pass the lambda function above to
+the `->check()` method of `Option`.
 
 The built-in validators for CLI11 are: