From 4d8f3cfc6896bd1d6b6079f1da4b3eaf38575737 Mon Sep 17 00:00:00 2001
From: Gary Gregory <garydgregory@gmail.com>
Date: Mon, 12 Feb 2024 08:37:18 -0500
Subject: [PATCH] Javadoc

---
 .../compress/java/util/jar/Pack200.java       | 27 +++++++++++--------
 1 file changed, 16 insertions(+), 11 deletions(-)

diff --git a/src/main/java/org/apache/commons/compress/java/util/jar/Pack200.java b/src/main/java/org/apache/commons/compress/java/util/jar/Pack200.java
index a7f9a929417..027a3718098 100644
--- a/src/main/java/org/apache/commons/compress/java/util/jar/Pack200.java
+++ b/src/main/java/org/apache/commons/compress/java/util/jar/Pack200.java
@@ -21,6 +21,7 @@
 import java.io.IOException;
 import java.io.InputStream;
 import java.io.OutputStream;
+import java.nio.file.Path;
 import java.security.AccessController;
 import java.security.PrivilegedAction;
 import java.util.Objects;
@@ -30,6 +31,7 @@
 import java.util.jar.JarOutputStream;
 
 import org.apache.commons.compress.harmony.archive.internal.nls.Messages;
+import org.apache.commons.io.input.BoundedInputStream;
 
 /**
  * Class factory for {@link Pack200.Packer} and {@link Pack200.Unpacker}.
@@ -137,14 +139,14 @@ public interface Packer {
         String UNKNOWN_ATTRIBUTE = "pack.unknown.attribute";//$NON-NLS-1$
 
         /**
-         * Add a listener for PropertyChange events
+         * Adds a listener for PropertyChange events
          *
          * @param listener the listener to listen if PropertyChange events occurs
          */
         void addPropertyChangeListener(PropertyChangeListener listener);
 
         /**
-         * Pack the specified JAR file to the specified output stream.
+         * Packs the specified JAR file to the specified output stream.
          *
          * @param in  JAR file to be compressed.
          * @param out stream of compressed data.
@@ -153,7 +155,7 @@ public interface Packer {
         void pack(JarFile in, OutputStream out) throws IOException;
 
         /**
-         * Pack the data from the specified jar input stream to the specified output stream.
+         * Packs the data from the specified jar input stream to the specified output stream.
          *
          * @param in  stream of uncompressed JAR data.
          * @param out stream of compressed data.
@@ -162,14 +164,14 @@ public interface Packer {
         void pack(JarInputStream in, OutputStream out) throws IOException;
 
         /**
-         * Returns a sorted map of the properties of this packer.
+         * Gets a sorted map of the properties of this packer.
          *
          * @return the properties of the packer.
          */
         SortedMap<String, String> properties();
 
         /**
-         * remove a listener
+         * Removes a listener
          *
          * @param listener listener to remove
          */
@@ -207,28 +209,28 @@ public interface Unpacker {
         String TRUE = "true";//$NON-NLS-1$
 
         /**
-         * add a listener for {@code PropertyChange} events.
+         * Adds a listener for {@code PropertyChange} events.
          *
          * @param listener the listener to listen if {@code PropertyChange} events occurs.
          */
         void addPropertyChangeListener(PropertyChangeListener listener);
 
         /**
-         * Returns a sorted map of the properties of this unpacker.
+         * Gets a sorted map of the properties of this unpacker.
          *
          * @return the properties of unpacker.
          */
         SortedMap<String, String> properties();
 
         /**
-         * remove a listener.
+         * Removes a listener.
          *
          * @param listener listener to remove.
          */
         void removePropertyChangeListener(PropertyChangeListener listener);
 
         /**
-         * Unpack the contents of the specified {@code File} to the specified JAR output stream.
+         * Unpacks the contents of the specified {@code File} to the specified JAR output stream.
          *
          * @param in  file to be uncompressed.
          * @param out JAR output stream of uncompressed data.
@@ -237,13 +239,16 @@ public interface Unpacker {
         void unpack(File in, JarOutputStream out) throws IOException;
 
         /**
-         * Unpack the specified stream to the specified JAR output stream.
+         * Unpacks the specified stream to the specified JAR output stream.
          *
          * @param in  stream to uncompressed.
          * @param out JAR output stream of uncompressed data.
          * @throws IOException if I/O exception occurs.
+         * @deprecated Use {@link #unpack(Path, BoundedInputStream, JarOutputStream)}.
          */
+        @Deprecated
         void unpack(InputStream in, JarOutputStream out) throws IOException;
+
     }
 
     /**
@@ -299,7 +304,7 @@ public static Pack200.Unpacker newUnpacker() {
     }
 
     /**
-     * Prevent this class from being instantiated.
+     * Prevents this class from being instantiated.
      */
     private Pack200() {
         // do nothing