diff --git a/src/collector/sort_key/order.rs b/src/collector/sort_key/order.rs index 989fe5d08..241fee619 100644 --- a/src/collector/sort_key/order.rs +++ b/src/collector/sort_key/order.rs @@ -44,7 +44,8 @@ impl Comparator 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 higher doc ids. +/// to the NaturalComparator. In presence of a tie, both version will retain the documents based on +/// descending `DocId`/`DocAddress`. #[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 afde27824..078a80a1f 100644 --- a/src/collector/top_score_collector.rs +++ b/src/collector/top_score_collector.rs @@ -23,10 +23,9 @@ use crate::{DocAddress, DocId, Order, Score, SegmentReader}; /// The theoretical complexity for collecting the top `K` out of `N` documents /// is `O(N + K)`. /// -/// This collector does not guarantee a stable sorting in case of a tie on the -/// document score, for stable sorting `PartialOrd` needs to resolve on other fields -/// like docid in case of score equality. -/// Only then, it is suitable for pagination. +/// 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. /// /// ```rust /// use tantivy::collector::TopDocs; @@ -500,10 +499,9 @@ where /// /// For TopN == 0, it will be relative expensive. /// -/// When using the natural comparator, the top N computer returns the top N elements in -/// descending order, as expected for a top N. The TopNComputer will tiebreak using `Reverse`: -/// i.e., the `DocId|DocAddress` are always sorted in descending order, and the `Comparator` type -/// is only applied to the `Score` type. +/// The TopNComputer will tiebreak using `Reverse`: +/// i.e., the `DocId|DocAddress` are always sorted in descending 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