Re: [PATCH] Btrfs: Improve btrfs_ioctl_search_key documentation

[Hans van Kranenburg <hans.van.kranenburg@mendix.com>]

On 06/05/2017 09:00 PM, Goffredo Baroncelli wrote:
> On 2017-06-05 17:27, Hans van Kranenburg wrote:
>> +	 * When doing a tree search, we're actually taking a slice from a linear
>> +	 * search space of 136-bit keys:
>> +	 *
>> +	 * Key of the first possible item to be returned:
>> +	 *   (min_objectid << 72) + (min_type << 64) + min_offset
>> +	 * Key of the last possible item to be returned:
>> +	 *   (max_objectid << 72) + (max_type << 64) + max_offset
>> +	 *
> As non English people, I prefer a less verbose [...]

Yeah, it's a bit meh... I started to change the text again and ended up
rewriting it in a different way for patch V2 (sending in a minute).

> [...] and more programmatic form, like:
> 
> +	 * When doing a tree search, we're actually taking a slice from a linear
> +	 * search space of 136-bit keys:
> +        *
> +	 * A key is returned if 
> +	 *   ((min_objectid << 72) + (min_type << 64) + min_offset  <=
> +        *        (objectid << 72) + (type << 64) + offset))  &&
> +	 *   ((max_objectid << 72) + (max_type << 64) + max_offset >= 
> +        *        (objectid << 72) + (type << 64) + offset))
> +        *

TBH, these lines mostly have an effect of dancing around before my eyes.

The point is, the search starts somewhere, end it ends somewhere. All
intermediate objects are returned. The min/max values are not applied as
a check to every key found in that range again. This way of explaining
("is returned if") adds to that wrong idea again imho.

>> +	 * [...] In other
>> +	 * words, they are not used to filter the type or offset of intermediate
>> +	 * keys encountered.
> 
> Even this is correct, I still find a bit complicate to fully understand the meaning.
> 
> I would prefer to replace "not used" with "not usable"... But as stated above I am not a native English people :-)

I'm dutch. ;) But for the user, using usable instead of used is nice
indeed, because it provides something that can be acted on, instead of
having something somewhere that "uses" it and apparently makes decisions
about what it does for some reason. Anyway, in the rewrite of that part
above, it's gone.

-- 
Hans van Kranenburg