patch-ids: document intentional const-casting in patch_id_neq()

The hashmap API requires the comparison function to take const pointers.
However, patch_id_neq() uses lazy evaluation to compute patch IDs on
demand. As established in b3dfeebb (rebase: avoid computing unnecessary
patch IDs, 2016-07-29), this avoids unnecessary work since not all
objects in the hashmap will eventually be compared.

Remove the ten-year-old "NEEDSWORK" comment and formally document
this intentional design trade-off.

Signed-off-by: Tian Yuchen <cat@malon.dev>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/patch-ids.c b/patch-ids.c
index a5683b462c6e7692ceff3218213b9747a9b6cc02..1fbc88cbec874ef2a923004279150900d51e7b02 100644 (file)
--- a/patch-ids.c
+++ b/patch-ids.c
@@ -41,7 +41,14 @@ static int patch_id_neq(const void *cmpfn_data,
                        const struct hashmap_entry *entry_or_key,
                        const void *keydata UNUSED)
 {
-       /* NEEDSWORK: const correctness? */
+       /*
+        * We drop the 'const' modifier here intentionally.
+        *
+        * Even though eptr and entry_or_key are const, we want to
+        * lazily compute their .patch_id members; see b3dfeebb (rebase:
+        * avoid computing unnecessary patch IDs, 2016-07-29). So we cast
+        * the constness away with container_of().
+        */
        struct diff_options *opt = (void *)cmpfn_data;
        struct patch_id *a, *b;