From 287052cb8b5e2c80fe0da9e185484bdc3d1ec1e3 Mon Sep 17 00:00:00 2001
From: Stu Hood <stuhood@gmail.com>
Date: Tue, 16 Dec 2025 16:50:21 -0800
Subject: [PATCH] Adjust docs again for ascending DocId order.

---
 src/collector/sort_key/order.rs      | 10 +++++-----
 src/collector/top_score_collector.rs | 10 +++++-----
 2 files changed, 10 insertions(+), 10 deletions(-)

diff --git a/src/collector/sort_key/order.rs b/src/collector/sort_key/order.rs
index d64db2f46..d6723a578 100644
--- a/src/collector/sort_key/order.rs
+++ b/src/collector/sort_key/order.rs
@@ -21,9 +21,9 @@ pub trait Comparator<T>: Send + Sync + std::fmt::Debug + Default {
         // TopNComputer sorts in descending order of the SortKey by default: we apply that ordering
         // here to ease comparison in testing.
         self.compare(&rhs.sort_key, &lhs.sort_key).then_with(|| {
-            // In case of a tie on the feature, we always sort by ascending `DocAddress` in order
-            // to ensure a stable sorting of the documents. See the TopNComputer docs for more
-            // information.
+            // In case of a tie on the sort key, we always sort by ascending `DocAddress` in order
+            // to ensure a stable sorting of the documents, regardless of the sort key's order.
+            // See the TopNComputer docs for more information.
             lhs.doc.cmp(&rhs.doc)
         })
     }
@@ -47,8 +47,8 @@ impl<T: PartialOrd> Comparator<T> for NaturalComparator {
 /// first.
 ///
 /// The ReverseComparator does not necessarily imply that the sort order is reversed compared
-/// to the NaturalComparator. In presence of a tie, both version will retain the documents based on
-/// descending `DocId`/`DocAddress`.
+/// to the NaturalComparator. In presence of a tie on the sort key, documents will always be
+/// sorted by ascending `DocId`/`DocAddress` in TopN results, regardless of the comparator.
 #[derive(Debug, Copy, Clone, Default, Serialize, Deserialize)]
 pub struct ReverseComparator;
 
diff --git a/src/collector/top_score_collector.rs b/src/collector/top_score_collector.rs
index 2a2aa520b..695b48016 100644
--- a/src/collector/top_score_collector.rs
+++ b/src/collector/top_score_collector.rs
@@ -25,7 +25,7 @@ use crate::{DocAddress, DocId, Order, Score, SegmentReader};
 ///
 /// This collector guarantees a stable sorting in case of a tie on the
 /// document score/sort key: The document address (`DocAddress`) is used as a tie breaker.
-/// It is always sorted in descending order, regardless of the `Order` used for the sort key.
+/// In case of a tie on the sort key, documents are always sorted by ascending `DocAddress`.
 ///
 /// ```rust
 /// use tantivy::collector::TopDocs;
@@ -499,13 +499,13 @@ where
 ///
 /// For TopN == 0, it will be relative expensive.
 ///
-/// The TopNComputer will tiebreak using `Reverse<D>`:
-/// i.e., the `DocId|DocAddress` are always sorted in descending order, regardless of the
-/// `Comparator` used for the `Score` type.
+/// The TopNComputer will tiebreak by using ascending `D` (DocId or DocAddress):
+/// i.e., in case of a tie on the sort key, the `DocId|DocAddress` are always sorted in
+/// ascending order, regardless of the `Comparator` used for the `Score` type.
 ///
 /// NOTE: Items must be `push`ed to the TopNComputer in ascending `DocId|DocAddress` order, as the
 /// threshold used to eliminate docs does not include the `DocId` or `DocAddress`: this provides
-/// the `Reverse<DocId|DocAddress>` behavior without additional comparisons.
+/// the ascending `DocId|DocAddress` tie-breaking behavior without additional comparisons.
 #[derive(Serialize, Deserialize)]
 #[serde(from = "TopNComputerDeser<Score, D, C>")]
 pub struct TopNComputer<Score, D, C> {