Javadoc, checkstyle and since tags

git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/io/trunk@462807 13f79535-47bb-0310-9956-ffa450edef68

Author: Stephen Colebourne

src/java/org/apache/commons/io/input/CountingInputStream.java

@@ -20,8 +20,11 @@
 import java.io.InputStream;
 
 /**
- * A decorating input stream that counts the number of bytes that
- * have passed through so far.
+ * A decorating input stream that counts the number of bytes that have passed
+ * through the stream so far.
+ * <p>
+ * A typical use case would be during debugging, to ensure that data is being
+ * read as expected.
  *
  * @author Henri Yandell
  * @author Marcelo Liberato
@@ -34,15 +37,21 @@ public class CountingInputStream extends ProxyInputStream {
 
     /**
      * Constructs a new CountingInputStream.
-     * @param in InputStream to delegate to
+     *
+     * @param in  the InputStream to delegate to
      */
     public CountingInputStream(InputStream in) {
         super(in);
     }
 
+    //-----------------------------------------------------------------------
     /**
-     * Increases the count by super.read(b)'s return count
-     * 
+     * Reads a number of bytes into the byte array, keeping count of the
+     * number read.
+     *
+     * @param b  the buffer into which the data is read, not null
+     * @return the total number of bytes read into the buffer, -1 if end of stream
+     * @throws IOException if an I/O error occurs
      * @see java.io.InputStream#read(byte[]) 
      */
     public int read(byte[] b) throws IOException {
@@ -52,8 +61,14 @@ public int read(byte[] b) throws IOException {
     }
 
     /**
-     * Increases the count by super.read(b, off, len)'s return count
+     * Reads a number of bytes into the byte array at a specific offset,
+     * keeping count of the number read.
      *
+     * @param b  the buffer into which the data is read, not null
+     * @param off  the start offset in the buffer
+     * @param len  the maximum number of bytes to read
+     * @return the total number of bytes read into the buffer, -1 if end of stream
+     * @throws IOException if an I/O error occurs
      * @see java.io.InputStream#read(byte[], int, int)
      */
     public int read(byte[] b, int off, int len) throws IOException {
@@ -63,19 +78,26 @@ public int read(byte[] b, int off, int len) throws IOException {
     }
 
     /**
-     * Increases the count by 1 if a byte is successfully read. 
+     * Reads the next byte of data adding to the count of bytes received
+     * if a byte is successfully read. 
      *
+     * @return the byte read, -1 if end of stream
+     * @throws IOException if an I/O error occurs
      * @see java.io.InputStream#read()
      */
     public int read() throws IOException {
         int found = super.read();
         this.count += (found >= 0) ? 1 : 0;
         return found;
     }
-    
+
     /**
-     * Increases the count by the number of skipped bytes.
-     * 
+     * Skips the stream over the specified number of bytes, adding the skipped
+     * amount to the count.
+     *
+     * @param length  the number of bytes to skip
+     * @return the actual number of bytes skipped
+     * @throws IOException if an I/O error occurs
      * @see java.io.InputStream#skip(long)
      */
     public long skip(final long length) throws IOException {
@@ -84,6 +106,7 @@ public long skip(final long length) throws IOException {
         return skip;
     }
 
+    //-----------------------------------------------------------------------
     /**
      * The number of bytes that have passed through this stream.
      * <p>
@@ -120,19 +143,21 @@ public synchronized int resetCount() {
      * result in incorrect count for files over 2GB.
      *
      * @return the number of bytes accumulated
+     * @since Commons IO 1.3
      */
     public long getByteCount() {
         return this.count;
     }
 
     /** 
-     * Set the count back to 0. 
+     * Set the byte count back to 0. 
      * <p>
      * NOTE: This method is a replacement for <code>resetCount()</code>
      * and was added because that method returns an integer which will
      * result in incorrect count for files over 2GB.
      *
-     * @return the count previous to resetting.
+     * @return the count previous to resetting
+     * @since Commons IO 1.3
      */
     public synchronized long resetByteCount() {
         long tmp = this.count;

src/java/org/apache/commons/io/output/CountingOutputStream.java

@@ -20,42 +20,71 @@
 import java.io.OutputStream;
 
 /**
- * Used in debugging, it counts the number of bytes that pass 
- * through it.
+ * A decorating output stream that counts the number of bytes that have passed
+ * through the stream so far.
+ * <p>
+ * A typical use case would be during debugging, to ensure that data is being
+ * written as expected.
  *
- * @author <a href="mailto:bayard@apache.org">Henri Yandell</a>
+ * @author Henri Yandell
  * @version $Id$
  */
 public class CountingOutputStream extends ProxyOutputStream {
 
+    /** The count of bytes that have passed. */
     private long count;
 
     /**
-     * Constructs a CountingOutputStream.
-     * @param out the OutputStream to write to
+     * Constructs a new CountingOutputStream.
+     * 
+     * @param out  the OutputStream to write to
      */
     public CountingOutputStream( OutputStream out ) {
         super(out);
     }
 
-    /** @see java.io.OutputStream#write(byte[]) */
+    //-----------------------------------------------------------------------
+    /**
+     * Writes the contents of the specified byte array to this output stream
+     * keeping count of the number of bytes written.
+     *
+     * @param b  the bytes to write, not null
+     * @throws IOException if an I/O error occurs
+     * @see java.io.OutputStream#write(byte[])
+     */
     public void write(byte[] b) throws IOException {
         count += b.length;
         super.write(b);
     }
 
-    /** @see java.io.OutputStream#write(byte[], int, int) */
+    /**
+     * Writes a portion of the specified byte array to this output stream
+     * keeping count of the number of bytes written.
+     *
+     * @param b  the bytes to write, not null
+     * @param off  the start offset in the buffer
+     * @param len  the maximum number of bytes to write
+     * @throws IOException if an I/O error occurs
+     * @see java.io.OutputStream#write(byte[], int, int)
+     */
     public void write(byte[] b, int off, int len) throws IOException {
         count += len;
         super.write(b, off, len);
     }
 
-    /** @see java.io.OutputStream#write(int) */
+    /**
+     * Writes a single byte to the output stream adding to the count of the
+     * number of bytes written.
+     *
+     * @param b  the byte to write
+     * @see java.io.OutputStream#write(int)
+     */
     public void write(int b) throws IOException {
         count++;
         super.write(b);
     }
 
+    //-----------------------------------------------------------------------
     /**
      * The number of bytes that have passed through this stream.
      * <p>
@@ -67,7 +96,7 @@ public void write(int b) throws IOException {
      * @deprecated use <code>getByteCount()</code> - see issue IO-84
      */
     public int getCount() {
-        return (int)getByteCount();
+        return (int) getByteCount();
     }
 
     /** 
@@ -81,36 +110,37 @@ public int getCount() {
       * @deprecated use <code>resetByteCount()</code> - see issue IO-84
       */
     public synchronized int resetCount() {
-        return (int)resetByteCount();
+        return (int) resetByteCount();
     }
 
     /**
      * The number of bytes that have passed through this stream.
      * <p>
-     * <strong>N.B.</strong> This method was introduced as an
-     * alternative for the <code>getCount()</code> method
-     * because that method returns an integer which will result
-     * in incorrect count for files over 2GB being returned.
+     * NOTE: This method is a replacement for <code>getCount()</code>.
+     * It was added because that method returns an integer which will
+     * result in incorrect count for files over 2GB.
      *
      * @return the number of bytes accumulated
+     * @since Commons IO 1.3
      */
     public long getByteCount() {
         return this.count;
     }
 
     /** 
-     * Set the count back to 0. 
+     * Set the byte count back to 0. 
      * <p>
-     * <strong>N.B.</strong> This method was introduced as an
-     * alternative for the <code>resetCount()</code> method
-     * because that method returns an integer which will result
-     * in incorrect count for files over 2GB being returned.
+     * NOTE: This method is a replacement for <code>resetCount()</code>.
+     * It was added because that method returns an integer which will
+     * result in incorrect count for files over 2GB.
      *
-     * @return the count previous to resetting.
+     * @return the count previous to resetting
+     * @since Commons IO 1.3
      */
     public synchronized long resetByteCount() {
         long tmp = this.count;
         this.count = 0;
         return tmp;
     }
+
 }