Adjust docs again for ascending DocId order.

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;
 

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> {