Update javadocs

Author: fkjellberg

src/main/java/org/apache/commons/compress/archivers/lha/LhaArchiveEntry.java

@@ -147,7 +147,7 @@ public int getCrcValue() {
     /**
      * Gets the operating system id if available for this entry.
      *
-     * @return operating system id if available
+     * @return operating system id or null if not available
      */
     public Integer getOsId() {
         return osId;
@@ -183,7 +183,7 @@ public Integer getUnixGroupId() {
     /**
      * Gets the MS-DOS file attributes if available for this entry.
      *
-     * @return MS-DOS file attributes if available
+     * @return MS-DOS file attributes or null if not available
      */
     public Integer getMsdosFileAttributes() {
         return msdosFileAttributes;

src/main/java/org/apache/commons/compress/archivers/lha/LhaArchiveInputStream.java

@@ -408,7 +408,7 @@ protected LhaArchiveEntry readHeaderLevel2(ByteBuffer buffer) throws IOException
     }
 
     /**
-     * Get the compression method from the header. It is always located at the same offset for all header levels.
+     * Gets the compression method from the header. It is always located at the same offset for all header levels.
      *
      * @param buffer the buffer containing the header data
      * @return compression method, e.g. -lh5-
@@ -436,7 +436,7 @@ protected static String getCompressionMethod(final ByteBuffer buffer) throws Arc
     }
 
     /**
-     * Get the pathname from the current position in the provided buffer. Any 0xFF bytes
+     * Gets the pathname from the current position in the provided buffer. Any 0xFF bytes
      * and '\' chars will be converted into the configured file path separator char.
      * Any leading file path separator char will be removed to avoid extracting to
      * absolute locations.
@@ -571,7 +571,7 @@ protected void parseExtendedHeader(final ByteBuffer extendedHeaderBuffer, final
     }
 
     /**
-     * Check if the compression method is a directory entry.
+     * Tests whether the compression method is a directory entry.
      *
      * @param compressionMethod the compression method
      * @return true if the compression method is a directory entry, false otherwise

src/main/java/org/apache/commons/compress/archivers/lha/package-info.java

@@ -18,6 +18,7 @@
  */
 
 /**
- * Provides stream classes for reading archives using the LHA format, also known as the LZH format or LHarc format.
+ * Provides stream classes for reading archives using the <a href="https://en.wikipedia.org/wiki/LHA_(file_format)">LHA</a> format,
+ * also known as the LZH format or LHarc format.
  */
 package org.apache.commons.compress.archivers.lha;

src/main/java/org/apache/commons/compress/compressors/lha/AbstractLhStaticHuffmanCompressorInputStream.java

@@ -33,27 +33,41 @@
 /**
  * This is an implementation of a static Huffman compressor input stream for LHA files that
  * supports lh4, lh5, lh6 and lh7 compression methods.
- *
- * This implementation is based on the documentation that can be found at
- * https://github.com/jca02266/lha/blob/master/Hacking_of_LHa
  */
 abstract class AbstractLhStaticHuffmanCompressorInputStream extends CompressorInputStream implements InputStreamStatistics {
-    // Constants for command tree decoding
-    private static final int COMMAND_DECODING_LENGTH_BITS = 5; // Number of bits used to encode the command decoding tree length
-    private static final int MAX_NUMBER_OF_COMMAND_DECODING_CODE_LENGTHS = 19; // Maximum number of codes in the command decoding tree
-
-    // Constants for command tree
-    private static final int COMMAND_TREE_LENGTH_BITS = 9; // Number of bits used to encode the command tree length
-
-    // Constants for code length
-    private static final int CODE_LENGTH_BITS = 3; // Number of bits used to encode the code length
+    /**
+     *  Number of bits used to encode the command decoding tree length.
+     */
+    private static final int COMMAND_DECODING_LENGTH_BITS = 5;
+    /**
+     * Maximum number of codes in the command decoding tree.
+     */
+    private static final int MAX_NUMBER_OF_COMMAND_DECODING_CODE_LENGTHS = 19;
+    /**
+     * Number of bits used to encode the command tree length.
+     */
+    private static final int COMMAND_TREE_LENGTH_BITS = 9;
+    /**
+     * Number of literal codes (0-255).
+     */
+    private static final int NUMBER_OF_LITERAL_CODES = 0x100;
+    /**
+     * Number of bits used to encode the code length.
+     */
+    private static final int CODE_LENGTH_BITS = 3;
     private static final int MAX_CODE_LENGTH = 16;
 
     private BitInputStream bin;
     private CircularBuffer buffer;
     private int blockSize;
-    private BinaryTree commandTree; // Command is either a literal or a copy command
-    private BinaryTree distanceTree; // Distance is the offset to copy from the sliding dictionary
+    /**
+     * Command is either a literal or a copy command.
+     */
+    private BinaryTree commandTree;
+    /**
+     * Distance is the offset to copy from the sliding dictionary.
+     */
+    private BinaryTree distanceTree;
 
     /**
      * Constructs a new CompressorInputStream which decompresses bytes read from the specified stream.
@@ -82,7 +96,7 @@ public void close() throws IOException {
     }
 
     /**
-     * Get the threshold for copying data from the sliding dictionary. This is the minimum
+     * Gets the threshold for copying data from the sliding dictionary. This is the minimum
      * possible number of bytes that will be part of a copy command.
      *
      * @return the copy threshold
@@ -92,14 +106,14 @@ protected int getCopyThreshold() {
     }
 
     /**
-     * Get the number of bits used for the dictionary size.
+     * Gets the number of bits used for the dictionary size.
      *
      * @return the number of bits used for the dictionary size
      */
     protected abstract int getDictionaryBits();
 
     /**
-     * Get the size of the dictionary.
+     * Gets the size of the dictionary.
      *
      * @return the size of the dictionary
      */
@@ -108,18 +122,23 @@ protected int getDictionarySize() {
     }
 
     /**
-     * Get the number of bits used for the distance.
+     * Gets the number of bits used for the distance.
      *
      * @return the number of bits used for the distance
      */
     protected abstract int getDistanceBits();
 
-    protected int getDistanceCodeSize() {
+    /**
+     * Gets the maximum number of distance codes in the distance tree.
+     *
+     * @return the maximum number of distance codes
+     */
+    protected int getMaxNumberOfDistanceCodes() {
         return getDictionaryBits() + 1;
     }
 
     /**
-     * Get the maximum match length for the copy command.
+     * Gets the maximum match length for the copy command.
      *
      * @return the maximum match length
      */
@@ -128,13 +147,13 @@ protected int getMaxMatchLength() {
     }
 
     /**
-     * Get the maximum number of commands in the command tree.
+     * Gets the maximum number of commands in the command tree.
      * This is 256 literals (0-255) and 254 copy lengths combinations (3-256).
      *
      * @return the maximum number of commands
      */
     protected int getMaxNumberOfCommands() {
-        return 256 + getMaxMatchLength() - getCopyThreshold() + 1;
+        return NUMBER_OF_LITERAL_CODES + getMaxMatchLength() - getCopyThreshold() + 1;
     }
 
     @Override
@@ -306,8 +325,8 @@ private BinaryTree readDistanceTree() throws IOException {
         // Number of code lengths to read
         final int numCodeLengths = readBits(getDistanceBits());
 
-        if (numCodeLengths > getDistanceCodeSize()) {
-            throw new CompressorException("Code length table has invalid size (%d > %d)", numCodeLengths, getDistanceCodeSize());
+        if (numCodeLengths > getMaxNumberOfDistanceCodes()) {
+            throw new CompressorException("Code length table has invalid size (%d > %d)", numCodeLengths, getMaxNumberOfDistanceCodes());
         } else if (numCodeLengths == 0) {
             // If numCodeLengths is zero, we read a single code length of getDistanceBits() bits and use as root of the tree
             return new BinaryTree(readBits(getDistanceBits()));

src/main/java/org/apache/commons/compress/compressors/lha/Lh4CompressorInputStream.java

@@ -43,7 +43,7 @@ protected int getDistanceBits() {
     }
 
     @Override
-    protected int getDistanceCodeSize() {
+    protected int getMaxNumberOfDistanceCodes() {
         return getDictionaryBits() + 2;
     }
 }

src/main/java/org/apache/commons/compress/compressors/lha/package-info.java

@@ -18,6 +18,6 @@
  */
 
 /**
- * Provides stream classes for decompressing streams found in LHA archives.
+ * Provides stream classes for decompressing streams found in <a href="https://en.wikipedia.org/wiki/LHA_(file_format)">LHA</a> archives.
  */
 package org.apache.commons.compress.compressors.lha;

src/test/java/org/apache/commons/compress/compressors/lha/Lh4CompressorInputStreamTest.java

@@ -40,7 +40,7 @@ void testConfiguration() throws IOException {
             assertEquals(12, in.getDictionaryBits());
             assertEquals(4096, in.getDictionarySize());
             assertEquals(4, in.getDistanceBits());
-            assertEquals(14, in.getDistanceCodeSize());
+            assertEquals(14, in.getMaxNumberOfDistanceCodes());
             assertEquals(256, in.getMaxMatchLength());
             assertEquals(510, in.getMaxNumberOfCommands());
         }

src/test/java/org/apache/commons/compress/compressors/lha/Lh5CompressorInputStreamTest.java

@@ -40,7 +40,7 @@ void testConfiguration() throws IOException {
             assertEquals(8192, in.getDictionarySize());
             assertEquals(13, in.getDictionaryBits());
             assertEquals(4, in.getDistanceBits());
-            assertEquals(14, in.getDistanceCodeSize());
+            assertEquals(14, in.getMaxNumberOfDistanceCodes());
             assertEquals(256, in.getMaxMatchLength());
             assertEquals(510, in.getMaxNumberOfCommands());
         }

src/test/java/org/apache/commons/compress/compressors/lha/Lh6CompressorInputStreamTest.java

@@ -40,7 +40,7 @@ void testConfiguration() throws IOException {
             assertEquals(15, in.getDictionaryBits());
             assertEquals(32768, in.getDictionarySize());
             assertEquals(5, in.getDistanceBits());
-            assertEquals(16, in.getDistanceCodeSize());
+            assertEquals(16, in.getMaxNumberOfDistanceCodes());
             assertEquals(256, in.getMaxMatchLength());
             assertEquals(510, in.getMaxNumberOfCommands());
         }

src/test/java/org/apache/commons/compress/compressors/lha/Lh7CompressorInputStreamTest.java

@@ -40,7 +40,7 @@ void testConfiguration() throws IOException {
             assertEquals(16, in.getDictionaryBits());
             assertEquals(65536, in.getDictionarySize());
             assertEquals(5, in.getDistanceBits());
-            assertEquals(17, in.getDistanceCodeSize());
+            assertEquals(17, in.getMaxNumberOfDistanceCodes());
             assertEquals(256, in.getMaxMatchLength());
             assertEquals(510, in.getMaxNumberOfCommands());
         }