mismatch and return value

[Mike Parker via Digitalmars-d-learn]

On Wednesday, 13 July 2016 at 11:10:11 UTC, ketmar wrote:
> On Wednesday, 13 July 2016 at 11:06:56 UTC, celavek wrote:
>> On Wednesday, 13 July 2016 at 10:41:44 UTC, ketmar wrote:
>> I understand your point but it should not be a matter of 
>> guessing.
>> It should be explicitly stated by the documentation.
>
> then people will start to complain that documentation is "too 
> wordy", hard to read and unnecessarily repeats the obvious 
> things.
>
> good documentation omits obvious things just 'cause they are 
> obvious. i believe that any sane person will read the 
> description and assume that `mismatch` will return tuple with 
> two empty ranges when there is no mismatch found.
>
> it's somewhat hard to keep the balance between "documenting 
> everything" and "make documentation easy to read", i think.

To be fair, I think it's only obvious to someone who has achieved 
a certain level of comfort and familiarity with ranges and the 
range-based functions in Phobos. This particular function could 
just as easily be inferred to return an empty tuple rather than a 
tuple of two empty ranges. Being more specific about the return 
value is only a few extra words that I wouldn't judge as being 
"too wordy".