hidingmyname opened a new issue, #16928:
URL: https://github.com/apache/lucene/issues/16928
### Summary
All six concrete codecs in `org.apache.lucene.tests.codecs.compressing` start
their class javadoc with "CompressionCodec that ...". No `CompressionCodec`
class exists anywhere in the repo. They all extend `CompressingCodec`, which
lives in the same package.
### Where
`lucene/test-framework/src/java/org/apache/lucene/tests/codecs/compressing/`:
```java
// dummy/DummyCompressingCodec.java:30
/** CompressionCodec that does not compress data, useful for testing. */
// DeflateWithPresetCompressingCodec.java:21
/** CompressionCodec that uses {@link DeflateWithPresetDictCompressionMode}.
*/
public class DeflateWithPresetCompressingCodec extends CompressingCodec {
// FastCompressingCodec.java:21
/** CompressionCodec that uses {@link CompressionMode#FAST} */
public class FastCompressingCodec extends CompressingCodec {
// FastDecompressionCompressingCodec.java:21
/** CompressionCodec that uses {@link CompressionMode#FAST_DECOMPRESSION} */
public class FastDecompressionCompressingCodec extends CompressingCodec {
// HighCompressionCompressingCodec.java:21
/** CompressionCodec that uses {@link CompressionMode#HIGH_COMPRESSION} */
public class HighCompressionCompressingCodec extends CompressingCodec {
// LZ4WithPresetCompressingCodec.java:21
/** CompressionCodec that uses {@link LZ4WithPresetDictCompressionMode}. */
public class LZ4WithPresetCompressingCodec extends CompressingCodec {
```
The base class, `CompressingCodec.java:35`:
```java
public abstract class CompressingCodec extends FilterCodec {
```
A search of `main` for `CompressionCodec` matches only these six comments.
### Why it matters
To be clear about scope: this is the test framework, not the core API, so it
matters much less than a wrong name in core javadoc.
It does show up in the published lucene-test-framework javadoc, and people
writing custom codecs or compression modes do read these classes as examples.
The `DummyCompressingCodec` comment even says it's in its own package "to
make
sure the oal.codecs.compressing classes are visible enough to let people
write
their own CompressionMode". "CompressionCodec" sounds like a real type and is
very close to `CompressionMode` and `CompressingCodec`, so a reader may go
looking for a third class that doesn't exist.
### Suggested fix
```diff
-/** CompressionCodec that does not compress data, useful for testing. */
+/** {@link CompressingCodec} that does not compress data, useful for
testing. */
```
```diff
-/** CompressionCodec that uses {@link
DeflateWithPresetDictCompressionMode}. */
+/** {@link CompressingCodec} that uses {@link
DeflateWithPresetDictCompressionMode}. */
```
```diff
-/** CompressionCodec that uses {@link CompressionMode#FAST} */
+/** {@link CompressingCodec} that uses {@link CompressionMode#FAST} */
```
```diff
-/** CompressionCodec that uses {@link CompressionMode#FAST_DECOMPRESSION} */
+/** {@link CompressingCodec} that uses {@link
CompressionMode#FAST_DECOMPRESSION} */
```
```diff
-/** CompressionCodec that uses {@link CompressionMode#HIGH_COMPRESSION} */
+/** {@link CompressingCodec} that uses {@link
CompressionMode#HIGH_COMPRESSION} */
```
```diff
-/** CompressionCodec that uses {@link LZ4WithPresetDictCompressionMode}. */
+/** {@link CompressingCodec} that uses {@link
LZ4WithPresetDictCompressionMode}. */
```
All six files already import or share a package with `CompressingCodec`,
since
they extend it, so the `{@link}` resolves without any other changes.
Plain-text
`CompressingCodec` would also work.
### Upstream reference
Lucene.NET fixed this in its port of the test framework in
apache/lucenenet@`e107e6eb5` ("SWEEP: Lucene.Net.TestFramework.Codecs: Fixed
documentation comments"):
```diff
---
a/src/Lucene.Net.TestFramework/Codecs/Compressing/Dummy/DummyCompressingCodec.cs
+++
b/src/Lucene.Net.TestFramework/Codecs/Compressing/Dummy/DummyCompressingCodec.cs
/// <summary>
- /// CompressionCodec that does not compress data, useful for testing.
</summary>
+ /// <see cref="CompressingCodec"/> that does not compress data, useful
for testing. </summary>
```
```diff
---
a/src/Lucene.Net.TestFramework/Codecs/Compressing/FastDecompressionCompressingCodec.cs
+++
b/src/Lucene.Net.TestFramework/Codecs/Compressing/FastDecompressionCompressingCodec.cs
/// <summary>
- /// CompressionCodec that uses <seealso
cref="CompressionMode#FAST_DECOMPRESSION"/> </summary>
+ /// <see cref="CompressingCodec"/> that uses <see
cref="CompressionMode.FAST_DECOMPRESSION"/>. </summary>
```
That fix was incomplete. The same commit only reformatted
`FastCompressingCodec` and `HighCompressionCompressingCodec`, and current
Lucene.NET still has:
```csharp
/// CompressionCodec that uses <see cref="CompressionMode.FAST"/>.
</summary>
/// CompressionCodec that uses <see
cref="CompressionMode.HIGH_COMPRESSION"/>. </summary>
```
The two preset-dictionary codecs were added after the 4.8 line that
Lucene.NET
ports, so they have no counterpart there. The suggested fix above covers all
six Java files.
I can submit a PR for this.
--
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]
