hidingmyname opened a new issue, #16934:
URL: https://github.com/apache/lucene/issues/16934
### Description
### Summary
`HighFreqTerms.DocFreqComparator` is documented as "Compares terms by
docTermFreq". There's no `docTermFreq` anywhere. The comparator compares
`TermStats.docFreq`. "docTermFreq" mixes up the two statistics `TermStats`
carries, `docFreq` and `totalTermFreq`, and the next comparator in the file
is
the one that actually compares `totalTermFreq`.
### Where
`lucene/misc/src/java/org/apache/lucene/misc/HighFreqTerms.java:128-158`:
```java
/** Compares terms by docTermFreq */
public static final class DocFreqComparator implements
Comparator<TermStats> {
@Override
public int compare(TermStats a, TermStats b) {
int res = Long.compare(a.docFreq, b.docFreq);
...
}
}
/** Compares terms by totalTermFreq */
public static final class TotalTermFreqComparator implements
Comparator<TermStats> {
@Override
public int compare(TermStats a, TermStats b) {
int res = Long.compare(a.totalTermFreq, b.totalTermFreq);
```
`lucene/misc/src/java/org/apache/lucene/misc/TermStats.java:21-26`:
```java
/** Holder for a term along with its statistics ({@link #docFreq} and {@link
#totalTermFreq}). */
public final class TermStats {
public BytesRef termtext;
public String field;
public int docFreq;
public long totalTermFreq;
```
The only match for `docTermFreq` on `main` is this comment.
### Why it matters
To be upfront: this is the `misc` module and a single-line class comment, so
it's minor.
The two comparators exist so you can choose which statistic `HighFreqTerms`
ranks by, and this javadoc is the only description of the choice. Doc
frequency (how many documents contain the term) and total term frequency (how
many times it occurs overall) give different rankings. A made-up name that's
halfway between them makes it unclear which one `DocFreqComparator` uses
unless you read the body.
### Suggested fix
```diff
- /** Compares terms by docTermFreq */
+ /** Compares terms by {@link TermStats#docFreq} */
public static final class DocFreqComparator implements
Comparator<TermStats> {
```
(or plain `docFreq`, to match the `totalTermFreq` comment below it)
### Upstream reference
Lucene.NET fixed this in its port in apache/lucenenet@`c9adcae89` ("Updated
Lucene.Net.Misc documentation"):
```diff
--- a/src/Lucene.Net.Misc/Misc/HighFreqTerms.cs
+++ b/src/Lucene.Net.Misc/Misc/HighFreqTerms.cs
/// <summary>
- /// Compares terms by docTermFreq
+ /// Compares terms by <see cref="TermStats.DocFreq"/>
/// </summary>
public sealed class DocFreqComparator : IComparer<TermStats>
```
Current Lucene.NET (the class has since been renamed `DocFreqComparer`):
```csharp
/// <summary>
/// Compares terms by <see cref="TermStats.DocFreq"/>
/// </summary>
public sealed class DocFreqComparer : IComparer<TermStats>
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: [email protected]
For queries about this service, please contact Infrastructure at:
[email protected]
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
