journal: Document generic_array_bisect()

It's not trivial to figure out that this function does not search
for an exact match for the given needle, but whichever object in
the given direction that's closest to the needle.

Let's add a documentation blurb to explain how the function works
for to help future developers looking at this function.

diff --git a/src/libsystemd/sd-journal/journal-file.c b/src/libsystemd/sd-journal/journal-file.c
index 6ee5697bc95379c0b011dde12594ef027ee8a233..ccf09596d423b2024be933d9dffda1c157ecbd0d 100644 (file)
--- a/src/libsystemd/sd-journal/journal-file.c
+++ b/src/libsystemd/sd-journal/journal-file.c
@@ -2356,6 +2356,19 @@ static int generic_array_bisect(
                 uint64_t *ret_offset,
                 uint64_t *ret_idx) {
 
+        /* Given an entry array chain, this function finds the object "closest" to the given needle in the
+         * chain, taking into account the provided direction. A function can be provided to determine how
+         * an object is matched against the given needle.
+         *
+         * Given a journal file, the offset of an object and the needle, the test_object() function should
+         * return TEST_LEFT if the needle is located earlier in the entry array chain, TEST_RIGHT if the
+         * needle is located later in the entry array chain and TEST_FOUND if the object matches the needle.
+         * If test_object() returns TEST_FOUND for a specific object, that object's information will be used
+         * to populate the return values of this function. If test_object() never returns TEST_FOUND, the
+         * return values are populated with the details of one of the objects closest to the needle. If the
+         * direction is DIRECTION_UP, the earlier object is used. Otherwise, the later object is used.
+         */
+
         uint64_t a, p, t = 0, i = 0, last_p = 0, last_index = UINT64_MAX;
         bool subtract_one = false;
         Object *array = NULL;