[commons-compress] 08/13: COMPRESS-540: Javadoc enhancement

[pe...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

peterlee pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/commons-compress.git

commit 543ac95593bcad8d656e27be1e2ce2e48cd26b4a
Author: theobisproject <th...@gmail.com>
AuthorDate: Fri Dec 25 21:37:14 2020 +0100

    COMPRESS-540: Javadoc enhancement
    
    - Add thread safety information for input streams
    - Use consistent capitalization and punctuation in Javadoc
    - Use html tags for better Javadoc formatting
---
 .../commons/compress/archivers/tar/TarArchiveEntry.java  | 16 ++++++++--------
 .../apache/commons/compress/archivers/tar/TarFile.java   | 14 +++++++++-----
 .../commons/compress/utils/BoundedNIOInputStream.java    |  1 +
 .../utils/BoundedSeekableByteChannelInputStream.java     |  1 +
 4 files changed, 19 insertions(+), 13 deletions(-)

diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
index 37e76c9..9153a5d 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarArchiveEntry.java
@@ -556,14 +556,14 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO
 
     /**
      * Construct an entry from an archive's header bytes for random access tar. File is set to null.
-     * @param headerBuf The header bytes from a tar archive entry.
-     * @param encoding encoding to use for file names
+     * @param headerBuf the header bytes from a tar archive entry.
+     * @param encoding encoding to use for file names.
      * @param lenient when set to true illegal values for group/userid, mode, device numbers and timestamp will be
      * ignored and the fields set to {@link #UNKNOWN}. When set to false such illegal fields cause an exception instead.
-     * @param dataOffset Position of the entry data in the random access file
+     * @param dataOffset position of the entry data in the random access file.
      * @since 1.21
-     * @throws IllegalArgumentException if any of the numeric fields have an invalid format
-     * @throws IOException on error
+     * @throws IllegalArgumentException if any of the numeric fields have an invalid format.
+     * @throws IOException on error.
      */
     public TarArchiveEntry(final byte[] headerBuf, final ZipEncoding encoding, final boolean lenient,
             final long dataOffset) throws IOException {
@@ -869,7 +869,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO
      * <p>This method is only useful for entries created from a {@code
      * File} or {@code Path} but not for entries read from an archive.</p>
      *
-     * @return This entry's file or null if the entry was not created from a file.
+     * @return this entry's file or null if the entry was not created from a file.
      */
     public File getFile() {
         if (file == null) {
@@ -884,7 +884,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO
      * <p>This method is only useful for entries created from a {@code
      * File} or {@code Path} but not for entries read from an archive.</p>
      *
-     * @return This entry's file or null if the entry was not created from a file.
+     * @return this entry's file or null if the entry was not created from a file.
      * @since 1.21
      */
     public Path getPath() {
@@ -1213,7 +1213,7 @@ public class TarArchiveEntry implements ArchiveEntry, TarConstants, EntryStreamO
 
     /**
      * Set the offset of the data for the tar entry.
-     * @param dataOffset the position of the data in the tar
+     * @param dataOffset the position of the data in the tar.
      * @since 1.21
      */
     public void setDataOffset(final long dataOffset) {
diff --git a/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java b/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
index f512d29..dc4ab20 100644
--- a/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
+++ b/src/main/java/org/apache/commons/compress/archivers/tar/TarFile.java
@@ -332,7 +332,7 @@ public class TarFile implements Closeable {
      * When reading from the non-zero input streams, the data is actually read from the original input stream.
      * The size of each input stream is introduced by the sparse headers.
      *
-     * NOTE : Some all-zero input streams and non-zero input streams have the size of 0. We DO NOT store the
+     * @implNote Some all-zero input streams and non-zero input streams have the size of 0. We DO NOT store the
      *        0 size input streams because they are meaningless.
      */
     private void buildSparseInputStreams() throws IOException {
@@ -398,24 +398,28 @@ public class TarFile implements Closeable {
     }
 
     /**
+     * <p>
      * For PAX Format 0.0, the sparse headers(GNU.sparse.offset and GNU.sparse.numbytes)
      * may appear multi times, and they look like:
-     *
+     * <pre>
      * GNU.sparse.size=size
      * GNU.sparse.numblocks=numblocks
      * repeat numblocks times
      *   GNU.sparse.offset=offset
      *   GNU.sparse.numbytes=numbytes
      * end repeat
+     * </pre>
      *
-     *
+     * <p>
      * For PAX Format 0.1, the sparse headers are stored in a single variable : GNU.sparse.map
-     *
+     * <pre>
      * GNU.sparse.map
      *    Map of non-null data chunks. It is a string consisting of comma-separated values "offset,size[,offset-1,size-1...]"
+     * </pre>
      *
-     *
+     * <p>
      * For PAX Format 1.X:
+     * <br>
      * The sparse map itself is stored in the file data block, preceding the actual file data.
      * It consists of a series of decimal numbers delimited by newlines. The map is padded with nulls to the nearest block boundary.
      * The first number gives the number of entries in the map. Following are map entries, each one consisting of two numbers
diff --git a/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java b/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java
index 6f8015a..2a692c0 100644
--- a/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java
+++ b/src/main/java/org/apache/commons/compress/utils/BoundedNIOInputStream.java
@@ -23,6 +23,7 @@ import java.nio.ByteBuffer;
 
 /**
  * NIO backed bounded input stream for reading a predefined amount of data from.
+ * @ThreadSafe this base class is thread safe but implementations must not be.
  * @since 1.21
  */
 public abstract class BoundedNIOInputStream extends InputStream {
diff --git a/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java b/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java
index f8499bd..9da4a34 100644
--- a/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java
+++ b/src/main/java/org/apache/commons/compress/utils/BoundedSeekableByteChannelInputStream.java
@@ -24,6 +24,7 @@ import java.nio.channels.SeekableByteChannel;
 /**
  * InputStream that delegates requests to the underlying SeekableByteChannel, making sure that only bytes from a certain
  * range can be read.
+ * @ThreadSafe
  * @since 1.21
  */
 public class BoundedSeekableByteChannelInputStream extends BoundedNIOInputStream {