From 9e955a98715c52429f6eeac355506904a30d9f6f Mon Sep 17 00:00:00 2001
From: Johannes Kirschbauer <hsjobeki@gmail.com>
Date: Thu, 26 Dec 2024 16:12:28 +0100
Subject: [PATCH] doc: improve lib.compareLists documentation

---
 lib/lists.nix | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/lib/lists.nix b/lib/lists.nix
index ca436d7a9c94b5..f3065c31d922d6 100644
--- a/lib/lists.nix
+++ b/lib/lists.nix
@@ -1330,7 +1330,13 @@ rec {
           pairs);
 
   /**
-    Compare two lists element-by-element.
+    Compare two lists element-by-element with a comparison function `cmp`.
+
+    List elements are compared in order, the first non-equal pair of elements determines the result.
+
+    With `cmp := (a: b: a < b)`, the result is the same as comparing `listA < listB` directly.
+    Therefore `compareLists` is a generalization of the `<` operator with a customizable comparison function.
+    See also https://nix.dev/manual/nix/stable/language/operators#comparison for more information.
 
     # Inputs