Re: [PATCH] Btrfs: Improve btrfs_ioctl_search_key documentation

[Goffredo Baroncelli <kreijack@inwind.it>]

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 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))
+        *




> +	 * [...] 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 :-)

BR
G.Baroncelli
-- 
gpg @keyserver.linux.it: Goffredo Baroncelli <kreijackATinwind.it>
Key fingerprint BBF5 1610 0B64 DAC6 5F7D  17B2 0EDA 9B37 8B82 E0B5