Update transform validators documentation

[JonathanGzzBen]

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

[phlptp]

I was looking at this a little more. I think part of the confusion is that the transform method that takes a lambda uses a different signature from the std::function used in the validator object. So you can't just take that same lambda function and stick it in a Validator object even though they are compatible. You get very different results.

Also if the string return from the validator is not empty, then an exception gets generated from that. So it is permissible but not necessary to generate an exception for failed validation inside the function. You can just return an error message as the result.

Not sure if there is a better way to do that or not? The best I can think of right now is to add an error flag to the validator, so if validator failed then that flag must be set and then the input is always const and the output is either a message or the transformed value depending on whether the flag was set

[henryiii]

Returning the error message is preferred, since CLI11 might be able to run without exceptions enabled one day. That's why that signature is used.

I think this is a clear upgrade, but we could follow up with information about the validator std::function?

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 100.00%. Comparing base (e4ee3af) to head (2dc19a7).
Report is 31 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##              main      #689    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files           17        17            
  Lines         4546      4583    +37     
  Branches         0       981   +981     
==========================================
+ Hits          4546      4583    +37     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.