harmony-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From qi...@apache.org
Subject svn commit: r768698 [2/18] - in /harmony/enhanced/classlib/branches/java6: ./ modules/annotation/src/main/java/java/lang/annotation/ modules/archive/src/main/java/java/util/jar/ modules/archive/src/main/java/java/util/zip/ modules/auth/src/main/java/co...
Date Sun, 26 Apr 2009 12:30:06 GMT
Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Manifest.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Manifest.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Manifest.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Manifest.java Sun Apr 26 12:30:01 2009
@@ -34,8 +34,8 @@
 import org.apache.harmony.luni.util.ThreadLocalCache;
 
 /**
- * The Manifest class is used to obtain attribute information for a JarFile and
- * its entries.
+ * The {@code Manifest} class is used to obtain attribute information for a
+ * {@code JarFile} and its entries.
  */
 public class Manifest implements Cloneable {
     static final int LINE_LENGTH_LIMIT = 72;
@@ -75,21 +75,20 @@
     private int mainEnd;
 
     /**
-     * Constructs a new Manifest instance.
+     * Creates a new {@code Manifest} instance.
      */
     public Manifest() {
         super();
     }
 
     /**
-     * Constructs a new Manifest instance using the attributes obtained from is.
+     * Creates a new {@code Manifest} instance using the attributes obtained
+     * from the input stream.
      * 
      * @param is
-     *            InputStream to parse for attributes
-     * 
+     *            {@code InputStream} to parse for attributes.
      * @throws IOException
-     *             if an IO error occurs while creating this Manifest
-     * 
+     *             if an IO error occurs while creating this {@code Manifest}
      */
     public Manifest(InputStream is) throws IOException {
         super();
@@ -97,11 +96,11 @@
     }
 
     /**
-     * Constructs a new Manifest instance. The new instance will have the same
-     * attributes as those found in the parameter Manifest.
+     * Creates a new {@code Manifest} instance. The new instance will have the
+     * same attributes as those found in the parameter {@code Manifest}.
      * 
      * @param man
-     *            Manifest instance to obtain attributes from
+     *            {@code Manifest} instance to obtain attributes from.
      */
     @SuppressWarnings("unchecked")
     public Manifest(Manifest man) {
@@ -118,8 +117,8 @@
     }
 
     /**
-     * Resets the both the mainAttributes as well as the entry Attributes
-     * associated with this Manifest.
+     * Resets the both the main attributes as well as the entry attributes
+     * associated with this {@code Manifest}.
      */
     public void clear() {
         im = null;
@@ -128,20 +127,23 @@
     }
 
     /**
-     * Returns the Attributes associated with the parameter entry name
+     * Returns the {@code Attributes} associated with the parameter entry
+     * {@code name}.
      * 
      * @param name
-     *            The name of the entry to obtain Attributes for.
-     * @return The Attributes for the entry or null if the entry does not exist.
+     *            the name of the entry to obtain {@code Attributes} from.
+     * @return the Attributes for the entry or {@code null} if the entry does
+     *         not exist.
      */
     public Attributes getAttributes(String name) {
         return getEntries().get(name);
     }
 
     /**
-     * Returns a Map containing the Attributes for each entry in the Manifest.
+     * Returns a map containing the {@code Attributes} for each entry in the
+     * {@code Manifest}.
      * 
-     * @return A Map of entry attributes
+     * @return the map of entry attributes.
      */
     public Map<String, Attributes> getEntries() {
         initEntries();
@@ -161,19 +163,20 @@
     }
 
     /**
-     * Returns the main Attributes of the JarFile.
+     * Returns the main {@code Attributes} of the {@code JarFile}.
      * 
-     * @return Main Attributes associated with the source JarFile
+     * @return main {@code Attributes} associated with the source {@code
+     *         JarFile}.
      */
     public Attributes getMainAttributes() {
         return mainAttributes;
     }
 
     /**
-     * Creates a copy of this Manifest. The returned Manifest will equal the
-     * Manifest from which it was cloned.
+     * Creates a copy of this {@code Manifest}. The returned {@code Manifest}
+     * will equal the {@code Manifest} from which it was cloned.
      * 
-     * @return A copy of the receiver.
+     * @return a copy of this instance.
      */
     @Override
     public Object clone() {
@@ -182,26 +185,25 @@
 
     /**
      * Writes out the attribute information of the receiver to the specified
-     * OutputStream
+     * {@code OutputStream}.
      * 
      * @param os
-     *            The OutputStream to write to.
-     * 
+     *            The {@code OutputStream} to write to.
      * @throws IOException
-     *             If an error occurs writing the Manifest
+     *             If an error occurs writing the {@code Manifest}.
      */
     public void write(OutputStream os) throws IOException {
         write(this, os);
     }
 
     /**
-     * Constructs a new Manifest instance obtaining Attribute information from
-     * the parameter InputStream.
+     * Constructs a new {@code Manifest} instance obtaining attribute
+     * information from the specified input stream.
      * 
      * @param is
-     *            The InputStream to read from
+     *            The {@code InputStream} to read from.
      * @throws IOException
-     *             If an error occurs reading the Manifest.
+     *             If an error occurs reading the {@code Manifest}.
      */
     public void read(InputStream is) throws IOException {
         byte[] buf;
@@ -272,9 +274,9 @@
     }
     
     /**
-     * Returns the hashCode for this instance.
+     * Returns the hash code for this instance.
      * 
-     * @return This Manifest's hashCode
+     * @return this {@code Manifest}'s hashCode.
      */
     @Override
     public int hashCode() {
@@ -282,14 +284,13 @@
     }
 
     /**
-     * Determines if the receiver is equal to the parameter Object. Two
-     * Manifests are equal if they have identical main Attributes as well as
-     * identical entry Attributes.
+     * Determines if the receiver is equal to the parameter object. Two {@code
+     * Manifest}s are equal if they have identical main attributes as well as
+     * identical entry attributes.
      * 
      * @param o
-     *            The Object to compare against.
-     * @return <code>true</code> if the manifests are equal,
-     *         <code>false</code> otherwise
+     *            the object to compare against.
+     * @return {@code true} if the manifests are equal, {@code false} otherwise
      */
     @Override
     public boolean equals(Object o) {
@@ -318,16 +319,15 @@
     }
 
     /**
-     * Writes out the attribute information of the receiver to the specified
-     * OutputStream
+     * Writes out the attribute information of the specified manifest to the
+     * specified {@code OutputStream}
      * 
      * @param manifest
-     *            the attribute information of the receiver
+     *            the manifest to write out.
      * @param out
-     *            The OutputStream to write to.
-     * 
+     *            The {@code OutputStream} to write to.
      * @throws IOException
-     *             If an error occurs writing the Manifest
+     *             If an error occurs writing the {@code Manifest}.
      */
     static void write(Manifest manifest, OutputStream out) throws IOException {
         CharsetEncoder encoder = ThreadLocalCache.utf8Encoder.get();

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Pack200.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Pack200.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Pack200.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/jar/Pack200.java Sun Apr 26 12:30:01 2009
@@ -26,9 +26,7 @@
 import java.util.SortedMap;
 
 /**
- * Class that initialize Packer and Unpacker
- * 
- * See JSR200
+ * Class factory for {@link Pack200.Packer} and {@link Pack200.Unpacker}.
  */
 public abstract class Pack200 {
 
@@ -44,11 +42,14 @@
     }
 
     /**
-     * The method first read from system property for the classname of a Packer,
-     * if such property exists, the class shall be initialized; or the default
-     * Packer will be returned
+     * Returns a new instance of a packer engine.
+     * <p>
+     * The implementation of the packer engine is defined by the system property
+     * {@code 'java.util.jar.Pack200.Packer'}. If this system property is
+     * defined an instance of the specified class is returned, otherwise the
+     * system's default implementation is returned.
      * 
-     * @return a instance of Packer
+     * @return an instance of {@code Packer}
      */
     public static Pack200.Packer newPacker() {
         return (Packer) AccessController
@@ -71,11 +72,14 @@
     }
 
     /**
-     * The method first read from system property for the classname of a
-     * Unpacker, if such property exists, the class shall be initialized; or the
-     * default Unpacker will be returned
+     * Returns a new instance of a unpacker engine.
+     * <p>
+     * The implementation of the unpacker engine is defined by the system
+     * property {@code 'java.util.jar.Pack200.Unpacker'}. If this system
+     * property is defined an instance of the specified class is returned,
+     * otherwise the system's default implementation is returned.
      * 
-     * @return a instance of Unpacker
+     * @return a instance of {@code Unpacker}.
      */
     public static Pack200.Unpacker newUnpacker() {
         return (Unpacker) AccessController
@@ -95,24 +99,23 @@
     }
 
     /**
-     * interface of Packer
-     * 
-     * See JSR 200 specification
+     * The interface defining the API for converting a JAR file to an output
+     * stream in the Pack200 format.
      */
     public static interface Packer {
 
         /**
-         * the format of a class attribute name
+         * the format of a class attribute name.
          */
         static final String CLASS_ATTRIBUTE_PFX = "pack.class.attribute."; //$NON-NLS-1$
 
         /**
-         * the format of a code attribute name
+         * the format of a code attribute name.
          */
         static final String CODE_ATTRIBUTE_PFX = "pack.code.attribute."; //$NON-NLS-1$
 
         /**
-         * the deflation hint to set in the output archive
+         * the deflation hint to set in the output archive.
          */
         static final String DEFLATE_HINT = "pack.deflate.hint";//$NON-NLS-1$
 
@@ -122,48 +125,48 @@
         static final String EFFORT = "pack.effort";//$NON-NLS-1$
 
         /**
-         * a String of error
+         * a String representation for {@code error}.
          */
         static final String ERROR = "error";//$NON-NLS-1$
 
         /**
-         * a String of false
+         * a String representation of {@code false}.
          */
         static final String FALSE = "false";//$NON-NLS-1$
 
         /**
-         * the format of a field attribute name
+         * the format of a field attribute name.
          */
         static final String FIELD_ATTRIBUTE_PFX = "pack.field.attribute.";//$NON-NLS-1$
 
         /**
-         * a String of keep
+         * a String representation for {@code keep}.
          */
         static final String KEEP = "keep";//$NON-NLS-1$
 
         /**
-         * decide if all elements shall transmit in their original order
+         * decide if all elements shall transmit in their original order.
          */
         static final String KEEP_FILE_ORDER = "pack.keep.file.order";//$NON-NLS-1$
 
         /**
-         * a String of latest
+         * a String representation for {@code latest}.
          */
         static final String LATEST = "latest";//$NON-NLS-1$
 
         /**
-         * the format of a method attribute name
+         * the format of a method attribute name.
          */
         static final String METHOD_ATTRIBUTE_PFX = "pack.method.attribute.";//$NON-NLS-1$
 
         /**
-         * Packer shall attempt to determine the latest modification time if
-         * this is set to LASTEST
+         * if it shall attempt to determine the latest modification time if this
+         * is set to {@code LATEST}.
          */
         static final String MODIFICATION_TIME = "pack.modification.time";//$NON-NLS-1$
 
         /**
-         * a String of pass
+         * a String representation of {@code pass}.
          */
         static final String PASS = "pass";//$NON-NLS-1$
 
@@ -173,7 +176,7 @@
         static final String PASS_FILE_PFX = "pack.pass.file.";//$NON-NLS-1$
 
         /**
-         * packer progress as a percentage
+         * packer progress as a percentage.
          */
         static final String PROGRESS = "pack.progress";//$NON-NLS-1$
 
@@ -183,12 +186,12 @@
         static final String SEGMENT_LIMIT = "pack.segment.limit";//$NON-NLS-1$
 
         /**
-         * a String of strip
+         * a String representation of {@code strip}.
          */
         static final String STRIP = "strip";//$NON-NLS-1$
 
         /**
-         * a String of true
+         * a String representation of {@code true}.
          */
         static final String TRUE = "true";//$NON-NLS-1$
 
@@ -198,32 +201,34 @@
         static final String UNKNOWN_ATTRIBUTE = "pack.unknown.attribute";//$NON-NLS-1$
 
         /**
-         * 
-         * @return the properties of packer
+         * Returns a sorted map of the properties of this packer.
+         *
+         * @return the properties of the packer.
          */
         SortedMap<String, String> properties();
 
         /**
-         * Pack jarfile with pack arithmetic
+         * Pack the specified JAR file to the specified output stream.
          * 
          * @param in
-         *            jarfile to be compact
+         *            JAR file to be compressed.
          * @param out
-         *            stream of compact data
+         *            stream of compressed data.
          * @throws IOException
-         *             if I/O exception occurs
+         *             if I/O exception occurs.
          */
         void pack(JarFile in, OutputStream out) throws IOException;
 
         /**
-         * Pack jarStream with pack arithmetic
+         * Pack the data from the specified jar input stream to the specified
+         * output stream.
          * 
          * @param in
-         *            stream of uncompact jar data
+         *            stream of uncompressed JAR data.
          * @param out
-         *            stream of compact data
+         *            stream of compressed data.
          * @throws IOException
-         *             if I/O exception occurs
+         *             if I/O exception occurs.
          */
         void pack(JarInputStream in, OutputStream out) throws IOException;
 
@@ -245,81 +250,83 @@
     }
 
     /**
-     * interface of unpacker
-     * 
-     * See JSR 200 specification
+     * The interface defining the API for converting a packed stream in the
+     * Pack200 format to a JAR file.
      */
     public static interface Unpacker {
 
         /**
          * The String indicating if the unpacker should ignore all transmitted
-         * values,can be replaced by either true or false
+         * values,can be replaced by either {@code true} or {@code false}.
          */
         static final String DEFLATE_HINT = "unpack.deflate.hint";//$NON-NLS-1$
 
         /**
-         * a String of false
+         * a String representation of {@code false}.
          */
         static final String FALSE = "false";//$NON-NLS-1$
 
         /**
-         * a String of keep
+         * a String representation of {@code keep}.
          */
         static final String KEEP = "keep";//$NON-NLS-1$
 
         /**
-         * the progress as a percentage
+         * the progress as a {@code percentage}.
          */
         static final String PROGRESS = "unpack.progress";//$NON-NLS-1$
 
         /**
-         * a String of true
+         * a String representation of {@code true}.
          */
         static final String TRUE = "true";//$NON-NLS-1$
 
         /**
-         * 
-         * @return the properties of unpacker
+         * Returns a sorted map of the properties of this unpacker.
+         *
+         * @return the properties of unpacker.
          */
         SortedMap<String, String> properties();
 
         /**
-         * unpack stream into jarfile with pack arithmetic
+         * Unpack the specified stream to the specified JAR output stream.
          * 
          * @param in
-         *            stream to uncompact
+         *            stream to uncompressed.
          * @param out
-         *            jarstream of uncompact data
+         *            JAR output stream of uncompressed data.
          * @throws IOException
-         *             if I/O exception occurs
+         *             if I/O exception occurs.
          */
         void unpack(InputStream in, JarOutputStream out) throws IOException;
 
         /**
-         * unpack File into jarfile with pack arithmetic
+         * Unpack the contents of the specified {@code File} to the specified
+         * JAR output stream.
          * 
          * @param in
-         *            file to be uncompact
+         *            file to be uncompressed.
          * @param out
-         *            jarstream of uncompact data
+         *            JAR output stream of uncompressed data.
          * @throws IOException
-         *             if I/O exception occurs
+         *             if I/O exception occurs.
          */
         void unpack(File in, JarOutputStream out) throws IOException;
 
         /**
-         * add a listener for PropertyChange events
+         * add a listener for {@code PropertyChange} events.
          * 
          * @param listener
-         *            the listener to listen if PropertyChange events occurs
+         *            the listener to listen if {@code PropertyChange} events
+         *            occurs.
          */
         void addPropertyChangeListener(PropertyChangeListener listener);
 
         /**
-         * remove a listener
+         * remove a listener.
          * 
          * @param listener
-         *            listener to remove
+         *            listener to remove.
          */
         void removePropertyChangeListener(PropertyChangeListener listener);
     }

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Adler32.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Adler32.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Adler32.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Adler32.java Sun Apr 26 12:30:01 2009
@@ -18,58 +18,66 @@
 package java.util.zip;
 
 /**
- * The Adler32 class is used to compute the Adler32 Checksum from a set of data.
+ * The Adler-32 class is used to compute the {@code Adler32} checksum from a set
+ * of data. Compared to the CRC-32 algorithm it trades reliabilty for speed.
+ * Refer to RFC 1950 for the specification.
+ *
+ * @see CRC32
  */
 public class Adler32 implements java.util.zip.Checksum {
 
     private long adler = 1;
 
     /**
-     * Returns the Adler32 checksum for all input received
+     * Returns the {@code Adler32} checksum for all input received.
      * 
-     * @return The checksum for this instance
+     * @return The checksum for this instance.
      */
     public long getValue() {
         return adler;
     }
 
     /**
-     * Reset this instance to its initial checksum
+     * Reset this instance to its initial checksum.
      */
     public void reset() {
         adler = 1;
     }
 
     /**
-     * Update this Adler32 checksum using val.
+     * Update this {@code Adler32} checksum with the single byte provided as
+     * argument.
      * 
      * @param i
-     *            byte to update checksum with
+     *            the byte to update checksum with.
      */
     public void update(int i) {
         adler = updateByteImpl(i, adler);
     }
 
     /**
-     * Update this Adler32 checksum using the contents of buf.
+     * Update this {@code Adler32} checksum using the contents of {@code buf}.
      * 
      * @param buf
-     *            bytes to update checksum with
+     *            bytes to update checksum with.
      */
     public void update(byte[] buf) {
         update(buf, 0, buf.length);
     }
 
     /**
-     * Update this Adler32 checksum with the contents of buf, starting from
-     * offset and using nbytes of data.
+     * Update this {@code Adler32} checksum with the contents of {@code buf},
+     * starting from the offset provided and reading n bytes of data.
      * 
      * @param buf
-     *            buffer to obtain dat from
+     *            buffer to obtain data from.
      * @param off
-     *            offset i buf to copy from
+     *            offset in {@code buf} to start reading from.
      * @param nbytes
-     *            number of bytes from buf to use
+     *            number of bytes from {@code buf} to use.
+     * @throws ArrayIndexOutOfBoundsException
+     *             if {@code offset > buf.length} or {@code nbytes} is negative
+     *             or {@code offset + nbytes > buf.length}.
      */
     public void update(byte[] buf, int off, int nbytes) {
         // avoid int overflow, check null buf

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CRC32.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CRC32.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CRC32.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CRC32.java Sun Apr 26 12:30:01 2009
@@ -18,7 +18,8 @@
 package java.util.zip;
 
 /**
- * The CRC32 class is used to compute a CRC32 Checksum from a set of data.
+ * The CRC32 class is used to compute a CRC32 checksum from data provided as
+ * input value.
  */
 public class CRC32 implements java.util.zip.Checksum {
 
@@ -27,16 +28,16 @@
     long tbytes = 0L;
 
     /**
-     * Returns the CRC32 Checksum for all input received.
+     * Returns the CRC32 checksum for all input received.
      * 
-     * @return The checksum for this instance
+     * @return The checksum for this instance.
      */
     public long getValue() {
         return crc;
     }
 
     /**
-     * Returns the CRC32 checksum to it initial state.
+     * Resets the CRC32 checksum to it initial state.
      */
     public void reset() {
         tbytes = crc = 0;
@@ -44,32 +45,35 @@
     }
 
     /**
-     * Updates this Checksum with value val
+     * Updates this checksum with the byte value provided as integer.
+     *
+     * @param val
+     *            represents the byte to update the checksum.
      */
     public void update(int val) {
         crc = updateByteImpl((byte) val, crc);
     }
 
     /**
-     * Updates this Checksum with the bytes contained in buffer buf.
+     * Updates this checksum with the bytes contained in buffer {@code buf}.
      * 
      * @param buf
-     *            Buffer to update Checksum
+     *            the buffer holding the data to update the checksum with.
      */
     public void update(byte[] buf) {
         update(buf, 0, buf.length);
     }
 
     /**
-     * Updates this Checksum with nbytes of data from buffer buf, starting at
-     * offset off.
+     * Updates this checksum with n bytes of data obtained from buffer {@code
+     * buf}, starting at offset {@code off}.
      * 
      * @param buf
-     *            Buffer to update Checksum
+     *            the buffer to update the checksum.
      * @param off
-     *            Offset in buf to obtain data from
+     *            the offset in {@code buf} to obtain data from.
      * @param nbytes
-     *            Number of bytes to read from buf
+     *            the number of bytes to read from {@code buf}.
      */
     public void update(byte[] buf, int off, int nbytes) {
         // avoid int overflow, check null buf

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedInputStream.java Sun Apr 26 12:30:01 2009
@@ -21,21 +21,24 @@
 import java.io.InputStream;
 
 /**
- * The CheckedInputStream class is used to maintain a running Checksum of all
- * data read from a stream.
+ * The {@code CheckedInputStream} class is used to maintain a checksum at the
+ * same time as the data, on which the checksum is computed, is read from a
+ * stream. The purpose of this checksum is to establish data integrity,
+ * comparing the computed checksum against a published checksum value.
  */
 public class CheckedInputStream extends java.io.FilterInputStream {
 
     private final Checksum check;
 
     /**
-     * Constructs a new CheckedInputStream on InputStream is. The Checksum will
-     * be calculated using the algorithm implemented by csum.
+     * Constructs a new {@code CheckedInputStream} on {@code InputStream}
+     * {@code is}. The checksum will be calculated using the algorithm
+     * implemented by {@code csum}.
      * 
      * @param is
-     *            InputStream to calculate checksum from
+     *            the input stream to calculate checksum from.
      * @param csum
-     *            Type of Checksum to calculate
+     *            an entity implementing the checksum algorithm.
      */
     public CheckedInputStream(InputStream is, Checksum csum) {
         super(is);
@@ -43,10 +46,13 @@
     }
 
     /**
-     * Reads a byte of data from the underlying stream and recomputes the
-     * Checksum with the byte data.
+     * Reads one byte of data from the underlying input stream and updates the
+     * checksum with the byte data.
      * 
-     * @return -1 if end of stream, a single byte value otherwise
+     * @return {@code -1} at the end of the stream, a single byte value
+     *         otherwise.
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public int read() throws IOException {
@@ -58,10 +64,21 @@
     }
 
     /**
-     * Reads up to nbytes of data from the underlying stream, storing it in buf,
-     * starting at offset off. The Checksum is updated with the bytes read.
+     * Reads up to n bytes of data from the underlying input stream, storing it
+     * into {@code buf}, starting at offset {@code off}. The checksum is
+     * updated with the bytes read.
      * 
-     * @return Number of bytes read, -1 if end of stream
+     * @param buf
+     *            the byte array in which to store the bytes read.
+     * @param off
+     *            the initial position in {@code buf} to store the bytes read
+     *            from this stream.
+     * @param nbytes
+     *            the maximum number of bytes to store in {@code buf}.
+     * @return the number of bytes actually read or {@code -1} if arrived at the
+     *         end of the filtered stream while reading the data.
+     * @throws IOException
+     *             if this stream is closed or some I/O error occurs.
      */
     @Override
     public int read(byte[] buf, int off, int nbytes) throws IOException {
@@ -73,21 +90,23 @@
     }
 
     /**
-     * Returns the Checksum calculated on the stream thus far.
+     * Returns the checksum calculated on the stream read so far.
      * 
-     * @return A java.util.zip.Checksum
+     * @return the updated checksum.
      */
     public Checksum getChecksum() {
         return check;
     }
 
     /**
-     * Skip upto nbytes of data on the underlying stream. Any skipped bytes are
-     * added to the running Checksum value.
+     * Skip up to n bytes of data on the underlying input stream. Any skipped
+     * bytes are added to the running checksum value.
      * 
      * @param nbytes
-     *            long Number of bytes to skip
-     * @return Number of bytes skipped
+     *            the number of bytes to skip.
+     * @throws IOException
+     *             if this stream is closed or another I/O error occurs.
+     * @return the number of bytes skipped.
      */
     @Override
     public long skip(long nbytes) throws IOException {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/CheckedOutputStream.java Sun Apr 26 12:30:01 2009
@@ -21,21 +21,24 @@
 import java.io.OutputStream;
 
 /**
- * The CheckedOutputStream class is used to maintain a running Checksum of all
- * data written to a stream.
+ * The {@code CheckedOutputStream} class is used to maintain a running checksum
+ * of all data written to a stream. The purpose of this checksum is to establish
+ * data integrity, by publishing the checksum to other parties wanting to read
+ * the non corrupted data.
  */
 public class CheckedOutputStream extends java.io.FilterOutputStream {
 
     private final Checksum check;
 
     /**
-     * Constructs a new CheckedOutputStream on OutputStream os. The Checksum
-     * will be calculated using the algorithm implemented by csum.
+     * Constructs a new {@code CheckedOutputStream} on {@code OutputStream}
+     * {@code os}. The checksum is calculated using the algorithm implemented
+     * by {@code csum}.
      * 
      * @param os
-     *            OutputStream to calculate checksum from
+     *            the output stream to calculate checksum for.
      * @param cs
-     *            Type of Checksum to calculate
+     *            an entity implementing the checksum algorithm.
      */
     public CheckedOutputStream(OutputStream os, Checksum cs) {
         super(os);
@@ -43,23 +46,22 @@
     }
 
     /**
-     * Returns the Checksum calculated on the stream thus far.
+     * Returns the checksum calculated on the stream read so far.
      * 
-     * @return A java.util.zip.Checksum
+     * @return the updated checksum.
      */
     public Checksum getChecksum() {
         return check;
     }
 
     /**
-     * Writes byte value val to the underlying stream. The Checksum is updated
-     * with val.
+     * Writes the specified byte to the underlying stream. The checksum is
+     * updated with {@code val}.
      * 
      * @param val
-     *            Value of the byte to write out
-     * 
+     *            the data value to written to the output stream.
      * @throws IOException
-     *             if an IO error has occured
+     *             if an IO error has occurred.
      */
     @Override
     public void write(int val) throws IOException {
@@ -68,18 +70,18 @@
     }
 
     /**
-     * Writes nbytes of data from buf starting at offset off to the underlying
-     * stream. The Checksum is updated with the bytes written.
+     * Writes n bytes of data from {@code buf} starting at offset {@code off} to
+     * the underlying stream. The checksum is updated with the bytes written.
      * 
      * @param buf
-     *            data to write out
+     *            data written to the output stream.
      * @param off
-     *            the start offset of the data
+     *            the offset to start reading the data from {@code buf} written
+     *            to the output stream.
      * @param nbytes
-     *            number of bytes to write out
-     * 
+     *            number of bytes to write to the output stream.
      * @throws IOException
-     *             if an IO error has occured
+     *             if an IO error has occurred.
      */
     @Override
     public void write(byte[] buf, int off, int nbytes) throws IOException {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Checksum.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Checksum.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Checksum.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Checksum.java Sun Apr 26 12:30:01 2009
@@ -18,39 +18,41 @@
 package java.util.zip;
 
 /**
- * Interface to types that can compute a checksum value of given data.
+ * Holds information about a checksum which was computed with the methods
+ * implementing a checksum algorithm.
  */
 public interface Checksum {
 
     /**
-     * Answers the computed checksum value so far.
+     * Returns the current calculated checksum value.
      * 
-     * @return the checksum value
+     * @return the checksum.
      */
     public long getValue();
 
     /**
-     * Reinitialize the checksum computation to its starting value.
+     * Resets the checksum value applied before beginning calculations on a new
+     * stream of data.
      */
     public void reset();
 
     /**
-     * Update the checksum value based on the given byte array
-     * 
+     * Updates the checksum with the given bytes.
+     *
      * @param buf
-     *            the data used to update the checksum
+     *            the byte array from which to read the bytes.
      * @param off
-     *            the starting point for data values
+     *            the initial position in {@code buf} to read the bytes from.
      * @param nbytes
-     *            the number of bytes to consider
+     *            the number of bytes to read from {@code buf}.
      */
     public void update(byte[] buf, int off, int nbytes);
 
     /**
-     * Update the checksum value based on the given data value.
+     * Updates the checksum value with the given byte.
      * 
      * @param val
-     *            a single byte value
+     *            the byte to update the checksum with.
      */
     public void update(int val);
 }

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DataFormatException.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DataFormatException.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DataFormatException.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DataFormatException.java Sun Apr 26 12:30:01 2009
@@ -18,27 +18,26 @@
 package java.util.zip;
 
 /**
- * DataFormatException is used to indicate an error in the format of a
- * particular data stream.
+ * {@code DataFormatException} is used to indicate an error in the format of a
+ * particular data stream which is to be uncompressed.
  */
 public class DataFormatException extends Exception {
 
     private static final long serialVersionUID = 2219632870893641452L;
 
     /**
-     * Constructs a new instance of this class with its walkback filled in.
-     * 
+     * Constructs a new {@code DataFormatException} instance.
      */
     public DataFormatException() {
         super();
     }
 
     /**
-     * Constructs a new instance of this class with its walkback and message
-     * filled in.
-     * 
+     * Constructs a new {@code DataFormatException} instance with the specified
+     * message.
+     *
      * @param detailMessage
-     *            String The detail message for the exception.
+     *            the detail message for the exception.
      */
     public DataFormatException(String detailMessage) {
         super(detailMessage);

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Deflater.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Deflater.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Deflater.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Deflater.java Sun Apr 26 12:30:01 2009
@@ -20,36 +20,60 @@
 import org.apache.harmony.luni.platform.OSResourcesMonitor;
 
 /**
- * The Deflater class is used to compress bytes using the DEFLATE compression
- * algorithm. Deflation is performed by the ZLIB compression library.
- * 
+ * This class compresses data using the <i>DEFLATE</i> algorithm (see <a
+ * href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * <p>
+ * Basically this class is part of the API to the stream based ZLIB compression
+ * library and is used as such by {@code DeflaterOutputStream} and its
+ * descendants.
+ * <p>
+ * The typical usage of a {@code Deflater} instance outside this package
+ * consists of a specific call to one of its constructors before being passed to
+ * an instance of {@code DeflaterOutputStream}.
+ *
  * @see DeflaterOutputStream
  * @see Inflater
  */
 public class Deflater {
 
-    /** Constant value representing the best available compression level. */
+    /**
+     * Upper bound for the compression level range.
+     */
     public static final int BEST_COMPRESSION = 9;
 
-    /** Constant value representing the fastest available compression level. */
+    /**
+     * Lower bound for compression level range.
+     */
     public static final int BEST_SPEED = 1;
 
-    /** Constant value representing the default compression level. */
+    /**
+     * Usage of the default compression level.
+     */
     public static final int DEFAULT_COMPRESSION = -1;
 
-    /** Constant value representing the default compression strategy. */
+    /**
+     * Default value for compression strategy.
+     */
     public static final int DEFAULT_STRATEGY = 0;
 
-    /** Constant value representing the deflate compression strategy. */
+    /**
+     * Default value for compression method.
+     */
     public static final int DEFLATED = 8;
 
-    /** Constant value representing the filtered compression strategy. */
+    /**
+     * Possible value for compression strategy.
+     */
     public static final int FILTERED = 1;
 
-    /** Constant value representing the Huffman compression strategy. */
+    /**
+     * Possible value for compression strategy.
+     */
     public static final int HUFFMAN_ONLY = 2;
 
-    /** Constant value representing the no compression strategy. */
+    /**
+     * Possible value for compression level.
+     */
     public static final int NO_COMPRESSION = 0;
 
     private static final int Z_NO_FLUSH = 0;
@@ -84,35 +108,38 @@
     private int inLength;
 
     /**
-     * Constructs a new Deflater instance with default compression level and
-     * strategy.
+     * Constructs a new {@code Deflater} instance with default compression
+     * level. The strategy can be specified with {@link #setStrategy}, only. A
+     * header is added to the output by default; use constructor {@code
+     * Deflater(level, boolean)} if you need to omit the header.
      */
     public Deflater() {
         this(DEFAULT_COMPRESSION, false);
     }
 
     /**
-     * Constructs a new Deflater instance with compression level level and
-     * default compression strategy. THe compression level provided must be
-     * between 0 and 9.
+     * Constructs a new {@code Deflater} instance with a specific compression
+     * level. The strategy can be specified with {@code setStrategy}, only. A
+     * header is added to the output by default; use
+     * {@code Deflater(level, boolean)} if you need to omit the header.
      * 
      * @param level
-     *            the compression level to use
+     *            the compression level in the range between 0 and 9.
      */
     public Deflater(int level) {
         this(level, false);
     }
 
     /**
-     * Constructs a new Deflater instance with compression level level and
-     * default compression strategy. If the noHeader parameter is specified then
-     * no ZLIB header will be written as part of the compressed output. The
-     * compression level specified must be between 0 and 9.
+     * Constructs a new {@code Deflater} instance with a specific compression
+     * level. If noHeader is passed as true no ZLib header is added to the
+     * output. In a ZIP archive every entry (compressed file) comes with such a
+     * header. The strategy can be specified with the setStrategy method, only.
      * 
      * @param level
-     *            the compression level to use
+     *            the compression level in the range between 0 and 9.
      * @param noHeader
-     *            if true do not write the ZLIB header
+     *            {@code true} indicates that no ZLIB header should be written.
      */
     public Deflater(int level, boolean noHeader) {
         super();
@@ -125,31 +152,29 @@
     }
 
     /**
-     * Deflates data into the supplied buffer
+     * Deflates the data (previously passed to {@code setInput}) into the
+     * supplied buffer.
      * 
      * @param buf
-     *            buffer to store compressed data
-     * 
-     * @return number of bytes of compressed data stored
-     * 
+     *            buffer to write compressed data to.
+     * @return number of bytes of compressed data written to {@code buf}.
+     * @see #deflate(byte[], int, int)
      */
     public int deflate(byte[] buf) {
         return deflate(buf, 0, buf.length);
     }
 
     /**
-     * Deflates data into the supplied buffer using the region from off to
-     * nbytes - 1.
+     * Deflates data (previously passed to {@code setInput}) into a specific
+     * region within the supplied buffer.
      * 
      * @param buf
-     *            buffer to store compressed data
+     *            the buffer to write compressed data to.
      * @param off
-     *            offset inf buf to start storing data
+     *            the offset within {@code buf} at which to start writing to.
      * @param nbytes
-     *            number of bytes of compressed data to store in buf
-     * 
-     * @return number of bytes of compressed data stored
-     * 
+     *            maximum number of bytes of compressed data to be written.
+     * @return the number of bytes of compressed data written to {@code buf}.
      */
     public synchronized int deflate(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -173,10 +198,11 @@
     private synchronized native void endImpl(long handle);
 
     /**
-     * Frees all resources held onto by this Deflater. Any unused input or
-     * output is discarded. This is also called from the finalize method.
-     * 
-     * @see #finalize
+     * Frees all resources held onto by this deflating algorithm. Any unused
+     * input or output is discarded. While this method is used by {@code
+     * finalize()}, it can be called explicitly in order to free native
+     * resources before the next GC cycle. After {@code end()} was called other
+     * methods will typically throw an {@code IllegalStateException}.
      */
     public synchronized void end() {
         if (streamHandle != -1) {
@@ -192,10 +218,10 @@
     }
 
     /**
-     * Indicates to the Deflater that all uncompressed input has been provided
+     * Indicates to the {@code Deflater} that all uncompressed input has been provided
      * to it.
      * 
-     * @see #finished()
+     * @see #finished
      */
     public synchronized void finish() {
         flushParm = Z_FINISH;
@@ -205,7 +231,7 @@
      * Returns whether or not all provided data has been successfully
      * compressed.
      * 
-     * @return true if all data has been compressed, false otherwise
+     * @return true if all data has been compressed, false otherwise.
      */
     public synchronized boolean finished() {
         return finished;
@@ -216,9 +242,8 @@
      * preset dictionary is used getAdler() will return the Adler32 checksum of
      * the dictionary used.
      * 
-     * @return The Adler32 checksum of uncompressed data or preset dictionary if
-     *         used
-     * 
+     * @return the Adler32 checksum of uncompressed data or preset dictionary if
+     *         used.
      * @see #setDictionary(byte[])
      * @see #setDictionary(byte[], int, int)
      */
@@ -233,7 +258,7 @@
     private synchronized native int getAdlerImpl(long handle);
 
     /**
-     * Returns the total number of bytes of input consumed by the deflater.
+     * Returns the total number of bytes of input consumed by the {@code Deflater}.
      * 
      * @return number of bytes of input read.
      */
@@ -248,7 +273,7 @@
     private synchronized native long getTotalInImpl(long handle);
 
     /**
-     * Returns the total number of compressed bytes output by this Deflater.
+     * Returns the total number of compressed bytes output by this {@code Deflater}.
      * 
      * @return number of compressed bytes output.
      */
@@ -263,14 +288,14 @@
     private synchronized native long getTotalOutImpl(long handle);
 
     /**
-     * Indicates whether or not all bytes of uncompressed input have been
-     * consumed by the Deflater. If needsInput() answers true setInput() must be
-     * called before deflation can continue. If all bytes of uncompressed data
-     * have been provided to the Deflater finish() must be called to ensure the
-     * compressed data is output.
+     * Counterpart to setInput(). Indicates whether or not all bytes of
+     * uncompressed input have been consumed by the {@code Deflater}. If needsInput()
+     * returns true setInput() must be called before deflation can continue. If
+     * all bytes of uncompressed data have been provided to the {@code Deflater}
+     * finish() must be called to ensure the compressed data is output.
      * 
-     * @return True if input is required for deflation to continue, false
-     *         otherwise
+     * @return {@code true} if input is required for deflation to continue,
+     *         {@code false} otherwise.
      * @see #finished()
      * @see #setInput(byte[])
      * @see #setInput(byte[], int, int)
@@ -283,12 +308,12 @@
     }
 
     /**
-     * Resets the <code>Deflater</code> to accept new input without affecting
-     * any previously made settings for the compression strategy or level. This
-     * operation <i>must</i> be called after <code>finished()</code> returns
-     * <code>true</code> if the <code>Deflater</code> is to be reused.
+     * Resets the {@code Deflater} to accept new input without affecting any
+     * previously made settings for the compression strategy or level. This
+     * operation <i>must</i> be called after {@code finished()} returns
+     * {@code true} if the {@code Deflater} is to be reused.
      * 
-     * @see #finished()
+     * @see #finished
      */
     public synchronized void reset() {
         if (streamHandle == -1) {
@@ -304,30 +329,31 @@
     private synchronized native void resetImpl(long handle);
 
     /**
-     * Defines a dictionary to be used for compression by the receiver.
+     * Sets the dictionary to be used for compression by this {@code Deflater}.
+     * setDictionary() can only be called if this {@code Deflater} supports the writing
+     * of ZLIB headers. This is the default behaviour but can be overridden
+     * using {@code Deflater(int, boolean)}.
      * 
      * @param buf
-     *            the entire set of bytes comprising the dictionary
-     * @see #setDictionary(byte[], int, int)
+     *            the buffer containing the dictionary data bytes.
+     * @see Deflater#Deflater(int, boolean)
      */
     public void setDictionary(byte[] buf) {
         setDictionary(buf, 0, buf.length);
     }
 
     /**
-     * Sets the dictionary to be used for compression by this Deflater.
-     * 
-     * <code>setDictionary()</code> can only be called if this Deflater
-     * supports the writing of ZLIB headers. This is the default behaviour but
-     * can be overridden using <code>Deflater(int, boolean)</code>.
-     * 
+     * Sets the dictionary to be used for compression by this {@code Deflater}.
+     * setDictionary() can only be called if this {@code Deflater} supports the writing
+     * of ZLIB headers. This is the default behaviour but can be overridden
+     * using {@code Deflater(int, boolean)}.
+     *
      * @param buf
-     *            the byte array containing the dictionary
+     *            the buffer containing the dictionary data bytes.
      * @param off
-     *            offset into the byte array
+     *            the offset of the data.
      * @param nbytes
-     *            number of bytes comprising the dictionary
-     * 
+     *            the length of the data.
      * @see Deflater#Deflater(int, boolean)
      */
     public synchronized void setDictionary(byte[] buf, int off, int nbytes) {
@@ -347,27 +373,27 @@
             int nbytes, long handle);
 
     /**
-     * Sets the input buffer the Deflater will use to extract uncompressed bytes
+     * Sets the input buffer the {@code Deflater} will use to extract uncompressed bytes
      * for later compression.
      * 
      * @param buf
-     *            the input buffer
+     *            the buffer.
      */
     public void setInput(byte[] buf) {
         setInput(buf, 0, buf.length);
     }
 
     /**
-     * Sets the input buffer the Deflater will use to extract uncompressed bytes
+     * Sets the input buffer the {@code Deflater} will use to extract uncompressed bytes
      * for later compression. Input will be taken from the buffer region
      * starting at off and ending at nbytes - 1.
      * 
      * @param buf
-     *            the input data byte array
+     *            the buffer containing the input data bytes.
      * @param off
-     *            offset into the input bytes
+     *            the offset of the data.
      * @param nbytes
-     *            number of valid bytes in the input array
+     *            the length of the data.
      */
     public synchronized void setInput(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -436,12 +462,12 @@
     }
 
     /**
-     * Returns a long int of total number of bytes read by the Deflater. This
-     * method performs the same as getTotalIn except it returns a long value
+     * Returns a long int of total number of bytes read by the {@code Deflater}. This
+     * method performs the same as {@code getTotalIn} except it returns a long value
      * instead of an integer
      * 
      * @see #getTotalIn()
-     * @return bytes exactly read by deflater
+     * @return total number of bytes read by {@code Deflater}.
      */
     public synchronized long getBytesRead() {
         // Throw NPE here
@@ -452,12 +478,12 @@
     }
 
     /**
-     * Returns a long int of total number of bytes of read by the Deflater. This
-     * method performs the same as getTotalOut except it returns a long value
-     * instead of an integer
+     * Returns a long int of total number of bytes of read by the {@code Deflater}. This
+     * method performs the same as {@code getTotalOut} except it returns a long
+     * value instead of an integer
      * 
      * @see #getTotalOut()
-     * @return bytes exactly write by deflater
+     * @return bytes exactly write by {@code Deflater}
      */
     public synchronized long getBytesWritten() {
         // Throw NPE here

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/DeflaterOutputStream.java Sun Apr 26 12:30:01 2009
@@ -24,54 +24,68 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The DeflaterOutputStream class implements a stream filter for the writing of
- * compressed data to a stream. Compression is performed by an instance of
- * Deflater.
+ * This class provides an implementation of {@code FilterOutputStream} that
+ * compresses data using the <i>DEFLATE</i> algorithm. Basically it wraps the
+ * {@code Deflater} class and takes care of the buffering.
+ *
+ * @see Deflater
  */
 public class DeflaterOutputStream extends FilterOutputStream {
     static final int BUF_SIZE = 512;
 
+    /**
+     * The buffer for the data to be written to.
+     */
     protected byte[] buf;
 
+    /**
+     * The deflater used.
+     */
     protected Deflater def;
 
     boolean done = false;
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
-     * stream. The provided Deflater instance will be used to compress data.
+     * This constructor lets you pass the {@code Deflater} specifying the
+     * compression algorithm.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the {@code OutputStream} where to write the compressed data
+     *            to.
      * @param def
-     *            Deflater to perform compression
+     *            is the specific {@code Deflater} that is used to compress
+     *            data.
      */
     public DeflaterOutputStream(OutputStream os, Deflater def) {
         this(os, def, BUF_SIZE);
     }
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
+     * This is the most basic constructor. You only need to pass the {@code
+     * OutputStream} to which the compressed data shall be written to. The
+     * default settings for the {@code Deflater} and internal buffer are used.
+     * In particular the {@code Deflater} produces a ZLIB header in the output
      * stream.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the OutputStream where to write the compressed data to.
      */
     public DeflaterOutputStream(OutputStream os) {
         this(os, new Deflater());
     }
 
     /**
-     * Constructs a new DeflaterOutputStream instance using os as the underlying
-     * stream. The provided Deflater instance will be used to compress data. The
-     * internal buffer for storing compressed data will be of size bsize.
+     * This constructor lets you specify both the compression algorithm as well
+     * as the internal buffer size to be used.
      * 
      * @param os
-     *            OutputStream to receive compressed data
+     *            is the {@code OutputStream} where to write the compressed data
+     *            to.
      * @param def
-     *            Deflater to perform compression
+     *            is the specific {@code Deflater} that will be used to compress
+     *            data.
      * @param bsize
-     *            size of internal compression buffer
+     *            is the size to be used for the internal buffer.
      */
     public DeflaterOutputStream(OutputStream os, Deflater def, int bsize) {
         super(os);
@@ -89,8 +103,8 @@
      * Compress the data in the input buffer and write it to the underlying
      * stream.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs during deflation.
+     * @throws IOException
+     *             If an error occurs during deflation.
      */
     protected void deflate() throws IOException {
         int x = 0;
@@ -105,8 +119,9 @@
      * all underlying streams. This stream can no longer be used after close()
      * has been called.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs during close.
+     * @throws IOException
+     *             If an error occurs while closing the data compression
+     *             process.
      */
     @Override
     public void close() throws IOException {
@@ -118,12 +133,11 @@
     }
 
     /**
-     * Write any unwritten data to the underlying stream. Do not close the
-     * stream. This allows subsequent Deflater's to write to the same stream.
-     * This Deflater cannot be used again.
+     * Writes any unwritten data to the underlying stream. Does not close the
+     * stream.
      * 
-     * @exception java.io.IOException
-     *                If an error occurs.
+     * @throws IOException
+     *             If an error occurs.
      */
     public void finish() throws IOException {
         if (done) {
@@ -149,17 +163,17 @@
     }
 
     /**
-     * Compress data from a buffer and write it to the underlying stream.
+     * Compresses {@code nbytes} of data from {@code buf} starting at
+     * {@code off} and writes it to the underlying stream.
      * 
      * @param buffer
-     *            Buffer of data to compress
+     *            the buffer of data to compress.
      * @param off
-     *            offset in buffer to extract data from
+     *            offset in buffer to extract data from.
      * @param nbytes
-     *            Number of bytes of data to compress and write
-     * 
-     * @exception IOException
-     *                If an error occurs during writing.
+     *            the number of bytes of data to read from the buffer.
+     * @throws IOException
+     *             If an error occurs during writing.
      */
     @Override
     public void write(byte[] buffer, int off, int nbytes) throws IOException {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPInputStream.java Sun Apr 26 12:30:01 2009
@@ -24,7 +24,9 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The GZIPInputStream class is used to read data stored in the GZIP format.
+ * The {@code GZIPInputStream} class is used to read data stored in the GZIP
+ * format, reading and decompressing GZIP data from the underlying stream into
+ * its buffer.
  */
 public class GZIPInputStream extends InflaterInputStream {
 
@@ -36,36 +38,44 @@
 
     private static final int FNAME = 8;
 
-    /** Value of GZIP header magic number. */
+    /**
+     * The magic header for the GZIP format.
+     */
     public final static int GZIP_MAGIC = 0x8b1f;
 
+    /**
+     * The checksum algorithm used when handling uncompressed data.
+     */
     protected CRC32 crc = new CRC32();
 
+    /**
+     * Indicates the end of the input stream.
+     */
     protected boolean eos = false;
 
     /**
-     * Construct a GZIPInputStream to read from GZIP data from the underlying
-     * stream
-     * 
+     * Construct a {@code GZIPInputStream} to read from GZIP data from the
+     * underlying stream.
+     *
      * @param is
-     *            InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @throws IOException
-     *             if an IO error occurs reading the stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPInputStream(InputStream is) throws IOException {
         this(is, BUF_SIZE);
     }
 
     /**
-     * Construct a GZIPInputStream to read from GZIP data from the underlying
-     * stream. Set the internal buffer size to size
+     * Construct a {@code GZIPInputStream} to read from GZIP data from the
+     * underlying stream. Set the internal buffer size to {@code size}.
      * 
      * @param is
-     *            InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param size
-     *            Internal read buffer size
+     *            the internal read buffer size.
      * @throws IOException
-     *             if an IO exception occurs reading the stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPInputStream(InputStream is, int size) throws IOException {
         super(is, new Inflater(true), size);

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/GZIPOutputStream.java Sun Apr 26 12:30:01 2009
@@ -21,36 +21,40 @@
 import java.io.OutputStream;
 
 /**
- * The GZIPOutputStream class is used to write data to a stream in the GZIP
- * storage format.
+ * The {@code GZIPOutputStream} class is used to write data to a stream in the
+ * GZIP storage format.
  */
 public class GZIPOutputStream extends DeflaterOutputStream {
 
+    /**
+     * The checksum algorithm used when treating uncompressed data.
+     */
     protected CRC32 crc = new CRC32();
 
     /**
-     * Construct a new GZIPOutputStream to write data in GZIP format to the
-     * underlying stream.
+     * Construct a new {@code GZIPOutputStream} to write data in GZIP format to
+     * the underlying stream.
      * 
      * @param os
-     *            OutputStream to write to
+     *            the {@code OutputStream} to write data to.
      * @throws IOException
-     *             if an IO error occurs writing to the output stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPOutputStream(OutputStream os) throws IOException {
         this(os, BUF_SIZE);
     }
 
     /**
-     * Construct a new GZIPOutputStream to write data in GZIP format to the
-     * underlying stream. Set the internal compression buffer to sise size.
+     * Construct a new {@code GZIPOutputStream} to write data in GZIP format to
+     * the underlying stream. Set the internal compression buffer to size
+     * {@code size}.
      * 
      * @param os
-     *            OutputStream to write to
+     *            the {@code OutputStream} to write to.
      * @param size
-     *            Internal buffer size
+     *            the internal buffer size.
      * @throws IOException
-     *             if an IO error occurs writing to the output stream
+     *             if an {@code IOException} occurs.
      */
     public GZIPOutputStream(OutputStream os, int size) throws IOException {
         super(os, new Deflater(Deflater.DEFAULT_COMPRESSION, true), size);
@@ -64,7 +68,10 @@
 
     /**
      * Indicates to the stream that all data has been written out, and any GZIP
-     * terminal data can now be output.
+     * terminal data can now be written.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
      */
     @Override
     public void finish() throws IOException {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Inflater.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Inflater.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Inflater.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/Inflater.java Sun Apr 26 12:30:01 2009
@@ -20,11 +20,19 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * The Inflater class is used to decompress bytes using the DEFLATE compression
- * algorithm. Inflation is performed by the ZLIB compression library.
+ * This class uncompresses data that was compressed using the <i>DEFLATE</i>
+ * algorithm (see <a href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * <p>
+ * Basically this class is part of the API to the stream based ZLIB compression
+ * library and is used as such by {@code InflaterInputStream} and its
+ * descendants.
+ * <p>
+ * The typical usage of a {@code Inflater} outside this package consists of a
+ * specific call to one of its constructors before being passed to an instance
+ * of {@code InflaterInputStream}.
  * 
- * @see DeflaterOutputStream
- * @see Inflater
+ * @see InflaterInputStream
+ * @see Deflater
  */
 public class Inflater {
 
@@ -52,18 +60,21 @@
     private long streamHandle = -1;
 
     /**
-     * Constructs a new Inflater instance.
+     * This constructor creates an inflater that expects a header from the input
+     * stream. Use {@code Inflater(boolean)} if the input comes without a ZLIB
+     * header.
      */
     public Inflater() {
         this(false);
     }
 
     /**
-     * Constructs a new Inflater instance. If noHeader is true the Inflater will
-     * not attempt to read a ZLIB header.
-     * 
+     * This constructor allows to create an inflater that expects no header from
+     * the input stream.
+     *
      * @param noHeader
-     *            If true, read a ZLIB header from input.
+     *            {@code true} indicates that no ZLIB header comes with the
+     *            input.
      */
     public Inflater(boolean noHeader) {
         streamHandle = createStream(noHeader);
@@ -92,22 +103,24 @@
     }
 
     /**
-     * Indicates if the Inflater has inflated the entire deflated stream. If
-     * deflated bytes remain and needsInput returns true this method will return
-     * false. This method should be called after all deflated input is supplied
-     * to the Inflater.
+     * Indicates if the {@code Inflater} has inflated the entire deflated
+     * stream. If deflated bytes remain and {@code needsInput()} returns {@code
+     * true} this method will return {@code false}. This method should be
+     * called after all deflated input is supplied to the {@code Inflater}.
      * 
-     * @return True if all input has been inflated, false otherwise
+     * @return {@code true} if all input has been inflated, {@code false}
+     *         otherwise.
      */
     public synchronized boolean finished() {
         return finished;
     }
 
     /**
-     * Returns the Adler32 checksum of either all bytes inflated, or the
+     * Returns the <i>Adler32</i> checksum of either all bytes inflated, or the
      * checksum of the preset dictionary if one has been supplied.
      * 
-     * @return The Adler32 checksum associated with this Inflater.
+     * @return The <i>Adler32</i> checksum associated with this
+     *         {@code Inflater}.
      */
     public synchronized int getAdler() {
         if (streamHandle == -1) {
@@ -119,12 +132,11 @@
     private native synchronized int getAdlerImpl(long handle);
 
     /**
-     * Returns a long int of total number of bytes of input read by the
-     * Inflater. This method performs the same as getTotalIn except it returns a
-     * long value instead of an integer
-     * 
-     * @see #getTotalIn()
-     * @return Total bytes read
+     * Returns the total number of bytes read by the {@code Inflater}. This
+     * method performs the same as {@code getTotalIn()} except that it returns a
+     * {@code long} value instead of an integer.
+     *
+     * @return the total number of bytes read.
      */
     public synchronized long getBytesRead() {
         // Throw NPE here
@@ -135,12 +147,11 @@
     }
 
     /**
-     * Returns a long int of total number of bytes of input output by the
-     * Inflater. This method performs the same as getTotalOut except it returns
-     * a long value instead of an integer
-     * 
-     * @see #getTotalOut()
-     * @return Total bytes output
+     * Returns a the total number of bytes read by the {@code Inflater}. This
+     * method performs the same as {@code getTotalOut} except it returns a
+     * {@code long} value instead of an integer.
+     *
+     * @return the total bytes written to the output buffer.
      */
     public synchronized long getBytesWritten() {
         // Throw NPE here
@@ -161,9 +172,10 @@
     }
 
     /**
-     * Returns total number of bytes of input read by the Inflater.
+     * Returns total number of bytes of input read by the {@code Inflater}. The
+     * result value is limited by {@code Integer.MAX_VALUE}.
      * 
-     * @return Total bytes read
+     * @return the total number of bytes read.
      */
     public synchronized int getTotalIn() {
         if (streamHandle == -1) {
@@ -177,9 +189,10 @@
     private synchronized native long getTotalInImpl(long handle);
 
     /**
-     * Returns total number of bytes of input output by the Inflater.
+     * Returns total number of bytes written to the output buffer by the {@code
+     * Inflater}. The result value is limited by {@code Integer.MAX_VALUE}.
      * 
-     * @return Total bytes output
+     * @return the total bytes of output data written.
      */
     public synchronized int getTotalOut() {
         if (streamHandle == -1) {
@@ -193,32 +206,33 @@
     private native synchronized long getTotalOutImpl(long handle);
 
     /**
-     * Inflates bytes from current input and stores them in buf.
+     * Inflates bytes from current input and stores them in {@code buf}.
      * 
      * @param buf
-     *            Buffer to output inflated bytes
-     * @return Number of bytes inflated
-     * @exception DataFormatException
-     *                If the underlying stream is corrupted or was not DEFLATED
-     * 
+     *            the buffer where decompressed data bytes are written.
+     * @return the number of bytes inflated.
+     * @throws DataFormatException
+     *             if the underlying stream is corrupted or was not compressed
+     *             using a {@code Deflater}.
      */
     public int inflate(byte[] buf) throws DataFormatException {
         return inflate(buf, 0, buf.length);
     }
 
     /**
-     * Inflates up to nbytes bytes from current input and stores them in buf
-     * starting at off.
+     * Inflates up to n bytes from the current input and stores them in {@code
+     * buf} starting at {@code off}.
      * 
      * @param buf
-     *            Buffer to output inflated bytes
+     *            the buffer to write inflated bytes to.
      * @param off
-     *            Offset in buffer into which to store inflated bytes
+     *            the offset in buffer where to start writing decompressed data.
      * @param nbytes
-     *            Number of inflated bytes to store
-     * @exception DataFormatException
-     *                If the underlying stream is corrupted or was not DEFLATED
-     * @return Number of bytes inflated
+     *            the number of inflated bytes to write to {@code buf}.
+     * @throws DataFormatException
+     *             if the underlying stream is corrupted or was not compressed
+     *             using a {@code Deflater}.
+     * @return the number of bytes inflated.
      */
     public synchronized int inflate(byte[] buf, int off, int nbytes)
             throws DataFormatException {
@@ -256,11 +270,12 @@
 
     /**
      * Indicates whether the input bytes were compressed with a preset
-     * dictionary. This method should be called prior to inflate() to determine
-     * if a dictionary is required. If so setDictionary() should be called with
-     * the appropriate dictionary prior to calling inflate().
+     * dictionary. This method should be called prior to {@code inflate()} to
+     * determine whether a dictionary is required. If so {@code setDictionary()}
+     * should be called with the appropriate dictionary prior to calling {@code
+     * inflate()}.
      * 
-     * @return true if a preset dictionary is required for inflation.
+     * @return {@code true} if a preset dictionary is required for inflation.
      * @see #setDictionary(byte[])
      * @see #setDictionary(byte[], int, int)
      */
@@ -269,9 +284,10 @@
     }
 
     /**
-     * Answers whether more data is required in the input buffer.
+     * Indicates that input has to be passed to the inflater.
      * 
-     * @return true if the input buffer is empty, and false otherwise.
+     * @return {@code true} if {@code setInput} has to be called before
+     *         inflation can proceed.
      * @see #setInput(byte[])
      */
     public synchronized boolean needsInput() {
@@ -279,7 +295,8 @@
     }
 
     /**
-     * Resets the Inflater.
+     * Resets the {@code Inflater}. Should be called prior to inflating a new
+     * set of data.
      */
     public synchronized void reset() {
         if (streamHandle == -1) {
@@ -294,32 +311,33 @@
     private native synchronized void resetImpl(long handle);
 
     /**
-     * Sets the preset dictionary to be used for inflation.
-     * 
-     * <code>needsDictionary()</code> can be called to determine whether the
-     * current input was deflated using a preset dictionary.
+     * Sets the preset dictionary to be used for inflation to {@code buf}.
+     * {@code needsDictionary()} can be called to determine whether the current
+     * input was deflated using a preset dictionary.
      * 
      * @param buf
-     *            The buffer containing the dictionary bytes
-     * @see #needsDictionary()
+     *            The buffer containing the dictionary bytes.
+     * @see #needsDictionary
      */
     public synchronized void setDictionary(byte[] buf) {
         setDictionary(buf, 0, buf.length);
     }
 
     /**
-     * Sets the dictionary used to inflate the given data.
-     * 
+     * Like {@code setDictionary(byte[])}, allowing to define a specific region
+     * inside {@code buf} to be used as a dictionary.
+     * <p>
      * The dictionary should be set if the {@link #inflate(byte[])} returned
      * zero bytes inflated and {@link #needsDictionary()} returns
      * <code>true</code>.
      * 
      * @param buf
-     *            the bytes containing the dictionary
+     *            the buffer containing the dictionary data bytes.
      * @param off
-     *            offset into the buffer to the start of the dictionary
+     *            the offset of the data.
      * @param nbytes
-     *            length of the dictionary, in bytes
+     *            the length of the data.
+     * @see #needsDictionary
      */
     public synchronized void setDictionary(byte[] buf, int off, int nbytes) {
         if (streamHandle == -1) {
@@ -338,11 +356,11 @@
             int nbytes, long handle);
 
     /**
-     * Sets the current input to buf. This method should only be called if
-     * needsInput() returns true.
+     * Sets the current input to to be decrompressed. This method should only be
+     * called if {@code needsInput()} returns {@code true}.
      * 
      * @param buf
-     *            input buffer
+     *            the input buffer.
      * @see #needsInput
      */
     public synchronized void setInput(byte[] buf) {
@@ -350,16 +368,17 @@
     }
 
     /**
-     * Sets the current input to the region of buf starting at off and ending at
-     * nbytes - 1. This method should only be called if needsInput() returns
-     * true.
+     * Sets the current input to the region of the input buffer starting at
+     * {@code off} and ending at {@code nbytes - 1} where data is written after
+     * decompression. This method should only be called if {@code needsInput()}
+     * returns {@code true}.
      * 
      * @param buf
-     *            input buffer
+     *            the input buffer.
      * @param off
-     *            offset to read from in buffer
+     *            the offset to read from the input buffer.
      * @param nbytes
-     *            number of bytes to read
+     *            the number of bytes to read.
      * @see #needsInput
      */
     public synchronized void setInput(byte[] buf, int off, int nbytes) {

Modified: harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java
URL: http://svn.apache.org/viewvc/harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java?rev=768698&r1=768697&r2=768698&view=diff
==============================================================================
--- harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java (original)
+++ harmony/enhanced/classlib/branches/java6/modules/archive/src/main/java/java/util/zip/InflaterInputStream.java Sun Apr 26 12:30:01 2009
@@ -25,18 +25,30 @@
 import org.apache.harmony.archive.internal.nls.Messages;
 
 /**
- * InflaterOutputStream read data which has been compressed using the DEFLATE
- * compression method.
+ * This class provides an implementation of {@code FilterInputStream} that
+ * uncompresses data that was compressed using the <i>DEFLATE</i> algorithm
+ * (see <a href="http://www.gzip.org/algorithm.txt">specification</a>).
+ * Basically it wraps the {@code Inflater} class and takes care of the
+ * buffering.
  * 
  * @see Inflater
  * @see DeflaterOutputStream
  */
 public class InflaterInputStream extends FilterInputStream {
 
+    /**
+     * The inflater used for this stream.
+     */
     protected Inflater inf;
 
+    /**
+     * The input buffer used for decompression.
+     */
     protected byte[] buf;
 
+    /**
+     * The length of the buffer.
+     */
     protected int len;
 
     boolean closed;
@@ -46,38 +58,41 @@
     static final int BUF_SIZE = 512;
 
     /**
-     * Constructs a new InflaterOutputStream on is
+     * This is the most basic constructor. You only need to pass the {@code
+     * InputStream} from which the compressed data is to be read from. Default
+     * settings for the {@code Inflater} and internal buffer are be used. In
+     * particular the Inflater expects a ZLIB header from the input stream.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      */
     public InflaterInputStream(InputStream is) {
         this(is, new Inflater(), BUF_SIZE);
     }
 
     /**
-     * Constructs a new InflaterOutputStream on is, using the Inflater provided
-     * in inf.
+     * This constructor lets you pass a specifically initialized Inflater,
+     * for example one that expects no ZLIB header.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param inf
-     *            The Inflater to use for decompression
+     *            the specific {@code Inflater} for uncompressing data.
      */
     public InflaterInputStream(InputStream is, Inflater inf) {
         this(is, inf, BUF_SIZE);
     }
 
     /**
-     * Constructs a new InflaterOutputStream on is, using the Inflater provided
-     * in inf. The size of the inflation buffer is determined by bsize.
+     * This constructor lets you specify both the {@code Inflater} as well as
+     * the internal buffer size to be used.
      * 
      * @param is
-     *            The InputStream to read data from
+     *            the {@code InputStream} to read data from.
      * @param inf
-     *            The Inflater to use for decompression
+     *            the specific {@code Inflater} for uncompressing data.
      * @param bsize
-     *            size of the inflation buffer
+     *            the size to be used for the internal buffer.
      */
     public InflaterInputStream(InputStream is, Inflater inf, int bsize) {
         super(is);
@@ -94,9 +109,9 @@
     /**
      * Reads a single byte of decompressed data.
      * 
-     * @return byte read
+     * @return the byte read.
      * @throws IOException
-     *             If an error occurs reading
+     *             if an error occurs reading the byte.
      */
     @Override
     public int read() throws IOException {
@@ -108,18 +123,18 @@
     }
 
     /**
-     * Reads up to nbytes of decompressed data and stores it in buf starting at
-     * off.
+     * Reads up to {@code nbytes} of decompressed data and stores it in
+     * {@code buffer} starting at {@code off}.
      * 
      * @param buffer
-     *            Buffer to store into
+     *            the buffer to write data to.
      * @param off
-     *            offset in buffer to store at
+     *            offset in buffer to start writing.
      * @param nbytes
-     *            number of bytes to store
+     *            number of bytes to read.
      * @return Number of uncompressed bytes read
      * @throws IOException
-     *             If an error occurs reading
+     *             if an IOException occurs.
      */
     @Override
     public int read(byte[] buffer, int off, int nbytes) throws IOException {
@@ -177,6 +192,12 @@
         throw new ArrayIndexOutOfBoundsException();
     }
 
+    /**
+     * Fills the input buffer with data to be decompressed.
+     *
+     * @throws IOException
+     *             if an {@code IOException} occurs.
+     */
     protected void fill() throws IOException {
         if (closed) {
             throw new IOException(Messages.getString("archive.1E")); //$NON-NLS-1$
@@ -187,13 +208,13 @@
     }
 
     /**
-     * Skips up to nbytes of uncompressed data.
+     * Skips up to n bytes of uncompressed data.
      * 
      * @param nbytes
-     *            Number of bytes to skip
-     * @return Number of uncompressed bytes skipped
+     *            the number of bytes to skip.
+     * @return the number of uncompressed bytes skipped.
      * @throws IOException
-     *             If an error occurs skipping
+     *             if an error occurs skipping.
      */
     @Override
     public long skip(long nbytes) throws IOException {
@@ -215,10 +236,11 @@
     }
 
     /**
-     * Returns 0 if this stream has been closed, 1 otherwise.
+     * Returns whether data can be read from this stream.
      * 
+     * @return 0 if this stream has been closed, 1 otherwise.
      * @throws IOException
-     *             If an error occurs
+     *             If an error occurs.
      */
     @Override
     public int available() throws IOException {
@@ -233,10 +255,10 @@
     }
 
     /**
-     * Closes the stream
+     * Closes the input stream.
      * 
      * @throws IOException
-     *             If an error occurs closing the stream
+     *             If an error occurs closing the input stream.
      */
     @Override
     public void close() throws IOException {
@@ -249,13 +271,11 @@
     }
 
     /**
-     * Marks the current position in the stream.
-     * 
-     * This implementation overrides the supertype implementation to do nothing
-     * at all.
+     * Marks the current position in the stream. This implementation overrides
+     * the super type implementation to do nothing at all.
      * 
      * @param readlimit
-     *            of no use
+     *            of no use.
      */
     @Override
     public void mark(int readlimit) {
@@ -263,11 +283,10 @@
     }
 
     /**
-     * Reset the position of the stream to the last mark position.
-     * 
-     * This implementation overrides the supertype implementation and always
-     * throws an {@link IOException IOException} when called.
-     * 
+     * Reset the position of the stream to the last marked position. This
+     * implementation overrides the supertype implementation and always throws
+     * an {@link IOException IOException} when called.
+     *
      * @throws IOException
      *             if the method is called
      */
@@ -277,10 +296,10 @@
     }
 
     /**
-     * Answers whether the receiver implements mark semantics. This type does
-     * not support mark, so always responds <code>false</code>.
+     * Returns whether the receiver implements {@code mark} semantics. This type
+     * does not support {@code mark()}, so always responds {@code false}.
      * 
-     * @return false
+     * @return false, always
      */
     @Override
     public boolean markSupported() {



Mime
View raw message