From f8836aefa06e62b83f8fb135479b50ee8cf907ca Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=D0=9B=D0=B5=D0=BE=D0=BD=D0=B8=D0=B4=20=D0=AE=D1=80=D1=8C?=
 =?UTF-8?q?=D0=B5=D0=B2=20=28Leonid=20Yuriev=29?= <leo@yuriev.ru>
Date: Thu, 21 Mar 2024 21:28:12 +0300
Subject: [PATCH] =?UTF-8?q?mdbx-doc:=20=D0=B4=D0=BE=D0=BA=D1=83=D0=BC?=
 =?UTF-8?q?=D0=B5=D0=BD=D1=82=D0=B8=D1=80=D0=BE=D0=B2=D0=B0=D0=BD=D0=B8?=
 =?UTF-8?q?=D0=B5=20`mdbx=5Fcursor=5Fcompare()`.?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 mdbx.h     | 24 ++++++++++++++++++++++--
 src/core.c |  4 ++--
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/mdbx.h b/mdbx.h
index a7e78072..2c21cbf4 100644
--- a/mdbx.h
+++ b/mdbx.h
@@ -5024,10 +5024,30 @@ LIBMDBX_API MDBX_dbi mdbx_cursor_dbi(const MDBX_cursor *cursor);
  * \returns A non-zero error value on failure and 0 on success. */
 LIBMDBX_API int mdbx_cursor_copy(const MDBX_cursor *src, MDBX_cursor *dest);
 
-/** FIXME */
+/** \brief Сравнивает позицию курсоров.
+ * \ingroup c_cursors
+ *
+ * Функция предназначена для сравнения позиций двух
+ * инициализированных/установленных курсоров, связанных с одной транзакцией и
+ * одной таблицей (DBI-дескриптором).
+ * Если же курсоры связаны с разными транзакциями, либо с разными таблицами,
+ * либо один из них не инициализирован, то результат сравнения не определен
+ * (поведением может быть изменено в последующих версиях).
+ *
+ * \param [in] left             Левый курсор для сравнения позиций.
+ * \param [in] right            Правый курсор для сравнения позиций.
+ * \param [in] ignore_multival  Булевой флаг, влияющий на результат только при
+ *        сравнении курсоров для таблиц с мульти-значениями, т.е. с флагом
+ *        \ref MDBX_DUPSORT. В случае `true`, позиции курсоров сравниваются
+ *        только по ключам, без учета позиционирования среди мульти-значений.
+ *        Иначе, в случае `false`, при совпадении позиций по ключам,
+ *        сравниваются также позиции по мульти-значениям.
+ *
+ * \retval Значение со знаком в семантике оператора `<=>` (меньше нуля, ноль,
+ * либо больше нуля) как результат сравнения позиций курсоров. */
 LIBMDBX_API int mdbx_cursor_compare(const MDBX_cursor *left,
                                     const MDBX_cursor *right,
-                                    bool ignore_nested);
+                                    bool ignore_multival);
 
 /** \brief Retrieve by cursor.
  * \ingroup c_crud
diff --git a/src/core.c b/src/core.c
index 4fe17bfa..18465a64 100644
--- a/src/core.c
+++ b/src/core.c
@@ -19806,7 +19806,7 @@ int mdbx_cursor_renew(const MDBX_txn *txn, MDBX_cursor *mc) {
 }
 
 int mdbx_cursor_compare(const MDBX_cursor *l, const MDBX_cursor *r,
-                        bool ignore_nested) {
+                        bool ignore_multival) {
   const int incomparable = INT16_MAX + 1;
   if (unlikely(!l))
     return r ? -incomparable * 9 : 0;
@@ -19847,7 +19847,7 @@ int mdbx_cursor_compare(const MDBX_cursor *l, const MDBX_cursor *r,
   assert((l->mc_xcursor != nullptr) == (r->mc_xcursor != nullptr));
   if (unlikely((l->mc_xcursor != nullptr) != (r->mc_xcursor != nullptr)))
     return l->mc_xcursor ? incomparable * 2 : -incomparable * 2;
-  if (ignore_nested || !l->mc_xcursor)
+  if (ignore_multival || !l->mc_xcursor)
     return 0;
 
 #if MDBX_DEBUG