Javadoc: normalize verb usage and general tidying.

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

Author: garydgregory

src/java/org/apache/commons/codec/BinaryDecoder.java

@@ -53,20 +53,17 @@
  */
 package org.apache.commons.codec;
 
-
-
 /**
- * This interface defines common decoding methods for decoders
- * which decode byte arrays.
+ * Defines common decoding methods for byte arrays decoders.
  *
  * @author Tim O'Brien
- * @version $Id: BinaryDecoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: BinaryDecoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface BinaryDecoder extends Decoder {
 
     /**
-     * Decode a byte array and return the results of the decode
-     * as a byte array. 
+     * Decodes a byte array and returns the results as a byte array. 
      *
      * @param pArray A byte array which has been encoded with the
      *      appropriate encoder

src/java/org/apache/commons/codec/BinaryEncoder.java

@@ -54,16 +54,16 @@
 package org.apache.commons.codec;
 
 /**
- * A binary encoder contains methods common to all
- * encoders for binary data. 
+ * Defines common encoding methods for byte arrays encoders.
  * 
  * @author Tim O'Brien
- * @version $Id: BinaryEncoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: BinaryEncoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface BinaryEncoder extends Encoder {
 
     /**
-     * Encode a byte array and return the encoded data
+     * Encodes a byte array and return the encoded data
      * as a byte array.
      * 
      * @param pArray Data to be encoded

src/java/org/apache/commons/codec/Decoder.java

@@ -54,22 +54,27 @@
 package org.apache.commons.codec;
 
 /**
- * Forms one of the two interfaces at the center of the
- * codec package.  All decoders implement this interface
- * which allows a user to pass a generic Object to any
- * Decoder implementation in the codec package.
+ * <p>Provides the highest level of abstraction for Decoders.
+ * This is the sister interface of {@link Encoder}.  All
+ * Decoders implement this common generic interface.</p>
+ * 
+ * <p>Allows a user to pass a generic Object to any Decoder 
+ * implementation in the codec package.</p>
+ * 
+ * <p>One of the two interfaces at the center of the codec package.</p>
  * 
  * @author Tim O'Brien
- * @version $Id: Decoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: Decoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface Decoder {
 
     /**
-     * Decode an "encoded" Object and return a "decoded"
+     * Decodes an "encoded" Object and returns a "decoded"
      * Object.  Note that the implementation of this
      * interface will try to cast the Object parameter
      * to the specific type expected by a particular Decoder
-     * implementation.  If a ClassCastException occurs
+     * implementation.  If a {@link java.lang.ClassCastException} occurs
      * this decode method will throw a DecoderException.
      * 
      * @param pObject an object to "decode"

src/java/org/apache/commons/codec/DecoderException.java

@@ -54,16 +54,16 @@
 package org.apache.commons.codec;
 
 /**
- * The DecoderException is thrown when a Decoder has
- * encounter a failure condition during a decode. 
+ * Thrown when a Decoder has encountered a failure condition during a decode. 
  * 
  * @author Tim O'Brien
- * @version $Id: DecoderException.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: DecoderException.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public class DecoderException extends Exception {
 
     /**
-     * Create a DecoderException
+     * Creates a DecoderException
      * 
      * @param pMessage A message with meaning to a human
      */

src/java/org/apache/commons/codec/Encoder.java

@@ -54,21 +54,25 @@
 package org.apache.commons.codec;
 
 /**
- * Encoder is the sister interface of Decoder, it provides
- * the highest level of abstraction for Encoders.  All
- * Encoders implement this common generic interface.
+ * <p>Provides the highest level of abstraction for Encoders.
+ * This is the sister interface of {@link Decoder}.  All
+ * Encoder implement this common generic interface.</p>
+ * 
+ * <p>Allows a user to pass a generic Object to any Encoder 
+ * implementation in the codec package.</p>
+ * 
+ * <p>One of the two interfaces at the center of the codec package.</p>
  *
  * @author Tim O'Brien
- * @version $Id: Encoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: Encoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface Encoder {
 
     /**
-     * All encoders allow a library-user to pass an 
-     * Object and get an Object in return.  This function
-     * encodes an "Object" - returning the encoded content 
-     * as an Object.  The Objects here may just be byte[]
-     * or Strings depending on the implementation used.
+     * Encodes an "Object" and returns the encoded content 
+     * as an Object.  The Objects here may just be <code>byte[]</code>
+     * or <code>String</code>s depending on the implementation used.
      *   
      * @param pObject An object ot encode
      * 

src/java/org/apache/commons/codec/EncoderException.java

@@ -54,16 +54,16 @@
 package org.apache.commons.codec;
 
 /**
- * An EncoderException is thrown when there is a
- * failure condition during the encoding process.
+ * Thrown when there is a failure condition during the encoding process.
  * 
  * @author Tim O'Brien
- * @version $Id: EncoderException.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: EncoderException.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public class EncoderException extends Exception {
 
     /**
-     * Create a new instance of this exception with
+     * Creates a new instance of this exception with
      * an informative message.
      * 
      * @param pMessage a human intelligible message

src/java/org/apache/commons/codec/StringDecoder.java

@@ -54,17 +54,16 @@
 package org.apache.commons.codec;
 
 /**
- * A StringDecoder is a decoder which expects a String as
- * a method parameter and one that produces a String as the
- * output of the decoding process.
+ * Decodes a String into a String. 
  *
  * @author Tim O'Brien
- * @version $Id: StringDecoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: StringDecoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface StringDecoder extends Decoder {
 
     /**
-     * Decode a String and produce a String.
+     * Decodes a String and returns a String.
      * 
      * @param pString a String to encode
      * 

src/java/org/apache/commons/codec/StringEncoder.java

@@ -54,17 +54,16 @@
 package org.apache.commons.codec;
 
 /**
- * A StringEncoder is an encoder which expects a String as
- * a method parameter and one that produces a String as the
- * output of the Encoding process.
+ * Encodes a String into a String. 
  *
  * @author Tim O'Brien
- * @version $Id: StringEncoder.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: StringEncoder.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public interface StringEncoder extends Encoder {
 
     /**
-     * Encode a String and produce a String.
+     * Encodes a String and returns a String.
      * 
      * @param pString a String to encode
      * 

src/java/org/apache/commons/codec/StringEncoderComparator.java

@@ -65,28 +65,31 @@
  * form of a name such as Soundex.
  *
  * @author Tim O'Brien
- * @version $Id: StringEncoderComparator.java,v 1.3 2003/07/30 22:34:17 tobrien Exp $
+ * @author Gary Gregory
+ * @version $Id: StringEncoderComparator.java,v 1.4 2003/08/14 07:40:17 ggregory Exp $
  */
 public class StringEncoderComparator implements Comparator {
 
-    // Private encoder instance
+    /**
+     * Internal encoder instance.
+     */
     private StringEncoder stringEncoder;
 
     /**
-     * A no-arg, do-nothing constructor
+     * Constructs a new instance.
      */
     public StringEncoderComparator() {
     }
 
     /**
-     * Use the provided soundex algorithm.
+     * Constructs a new instance with the given soundex algorithm.
      */
     public StringEncoderComparator(StringEncoder en) {
         this.stringEncoder = en;
     }
 
     /**
-     * Compare 2 strings based not on the strings 
+     * Compares 2 strings based not on the strings 
      * themselves, but on an encoding of the two 
      * strings using the StringEncoder this Comparator
      * was created with.

src/java/org/apache/commons/codec/binary/package.html

@@ -1,5 +1,5 @@
 <html>
  <body>
-  Utilities for Base64 and Hexadecimal String encoding and decoding.
+  Base64 and Hexadecimal String encoding and decoding.
  </body>
 </html>