QPID-5980: more javadoc fixups

git-svn-id: https://svn.apache.org/repos/asf/qpid/trunk@1616792 13f79535-47bb-0310-9956-ffa450edef68

25 files changed, 64 insertions, 114 deletions

diff --git a/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java b/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java
index c81af9760b..220e33724a 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQCodecFactory.java
@@ -25,11 +25,6 @@ import org.apache.qpid.protocol.AMQVersionAwareProtocolSession;
 /**
  * AMQCodecFactory is a Mina codec factory. It supplies the encoders and decoders need to read and write the bytes to
  * the wire.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations.
- * <tr><td> Supply the protocol decoder. <td> {@link AMQDecoder}
- * </table>
  */
 public class AMQCodecFactory
 {
@@ -44,6 +39,7 @@ public class AMQCodecFactory
      *
      * @param expectProtocolInitiation <tt>true</tt> if the first frame received is going to be a protocol initiation
      *                                 frame, <tt>false</tt> if it is going to be a standard AMQ data block.
+     * @param session protocol session (connection)
      */
     public AMQCodecFactory(boolean expectProtocolInitiation, AMQVersionAwareProtocolSession session)
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java b/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java
index ffdb7e6573..3ccd7e2031 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/codec/AMQDecoder.java
@@ -46,17 +46,11 @@ import java.util.ListIterator;
  * protocol initiation decoder. It is a cumulative decoder, which means that it can accumulate data to decode in the
  * buffer until there is enough data to decode.
  *
- * <p/>One instance of this class is created per session, so any changes or configuration done at run time to the
+ * <p>One instance of this class is created per session, so any changes or configuration done at run time to the
  * decoder will only affect decoding of the protocol session data to which is it bound.
  *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Delegate protocol initiation to its decoder. <td> {@link ProtocolInitiation.Decoder}
- * <tr><td> Delegate AMQP data to its decoder. <td> {@link AMQDataBlockDecoder}
- * <tr><td> Accept notification that protocol initiation has completed.
- * </table>
- *
- * @todo If protocol initiation decoder not needed, then don't create it. Probably not a big deal, but it adds to the
+ * <p>
+ * TODO If protocol initiation decoder not needed, then don't create it. Probably not a big deal, but it adds to the
  *       per-session overhead.
  */
 public class AMQDecoder
@@ -78,6 +72,7 @@ public class AMQDecoder
      * Creates a new AMQP decoder.
      *
      * @param expectProtocolInitiation <tt>true</tt> if this decoder needs to handle protocol initiation.
+     * @param session protocol session (connection)
      */
     public AMQDecoder(boolean expectProtocolInitiation, AMQVersionAwareProtocolSession session)
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/exchange/ExchangeDefaults.java b/qpid/java/common/src/main/java/org/apache/qpid/exchange/ExchangeDefaults.java
index 5e59628fb6..9384002a72 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/exchange/ExchangeDefaults.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/exchange/ExchangeDefaults.java
@@ -20,19 +20,12 @@
  */
 package org.apache.qpid.exchange;
 
-import org.apache.qpid.framing.AMQShortString;
-
 /**
  * Defines the names of the standard AMQP exchanges that every AMQP broker should provide. These exchange names
  * and type are given in the specification.
  *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Defines the standard AMQP exchange names.
- * <tr><td> Defines the standard AMQP exchange types.
- * </table>
- *
- * @todo A type safe enum, might be more appropriate for the exchange types.
+ * <p>
+ * TODO A type safe enum, might be more appropriate for the exchange types.
  */
 public class ExchangeDefaults
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/ArithmeticExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/ArithmeticExpression.java
index 47d970cfbd..35a7c93043 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/ArithmeticExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/ArithmeticExpression.java
@@ -30,10 +30,6 @@ public abstract class ArithmeticExpression extends BinaryExpression
     protected static final int LONG = 2;
     protected static final int DOUBLE = 3;
 
-    /**
-     * @param left
-     * @param right
-     */
     public ArithmeticExpression(Expression left, Expression right)
     {
         super(left, right);
@@ -262,11 +258,6 @@ public abstract class ArithmeticExpression extends BinaryExpression
         return evaluate(lvalue, rvalue);
     }
 
-    /**
-     * @param lvalue
-     * @param rvalue
-     * @return
-     */
     protected abstract Object evaluate(Object lvalue, Object rvalue);
 
 }
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/BinaryExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/BinaryExpression.java
index 6467bbbe1f..47f97ea908 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/BinaryExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/BinaryExpression.java
@@ -83,7 +83,7 @@ public abstract class BinaryExpression implements Expression
      * Returns the symbol that represents this binary expression.  For example, addition is
      * represented by "+"
      *
-     * @return
+     * @return the expression symbol
      */
     public abstract String getExpressionSymbol();
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/BooleanExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/BooleanExpression.java
index 13e1604d5f..5b1cf54680 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/BooleanExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/BooleanExpression.java
@@ -28,7 +28,7 @@ public interface BooleanExpression extends Expression
 {
 
     /**
-     * @param message
+     * @param message message to match
      * @return true if the expression evaluates to Boolean.TRUE.
      */
     public boolean matches(FilterableMessage message);
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/ComparisonExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/ComparisonExpression.java
index 2cfb97dc6c..76f743000b 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/ComparisonExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/ComparisonExpression.java
@@ -74,9 +74,6 @@ public abstract class ComparisonExpression extends BinaryExpression implements B
 
         private Pattern likePattern;
 
-        /**
-         * @param right
-         */
         public LikeExpression(Expression right, String like, int escape)
         {
             super(right);
@@ -316,9 +313,9 @@ public abstract class ComparisonExpression extends BinaryExpression implements B
     }
 
     /**
-     * Only Numeric expressions can be used in >, >=, < or <= expressions.s
+     * Only Numeric expressions can be used in {@literal >, >=, < or <=} expressions.
      *
-     * @param expr
+     * @param expr expression to check
      */
     public static void checkLessThanOperand(Expression expr)
     {
@@ -341,10 +338,10 @@ public abstract class ComparisonExpression extends BinaryExpression implements B
     }
 
     /**
-     * Validates that the expression can be used in == or <> expression.
+     * Validates that the expression can be used in {@literal == or <>} expression.
      * Cannot not be NULL TRUE or FALSE literals.
      *
-     * @param expr
+     * @param expr expression to check
      */
     public static void checkEqualOperand(Expression expr)
     {
@@ -374,10 +371,6 @@ public abstract class ComparisonExpression extends BinaryExpression implements B
         }
     }
 
-    /**
-     * @param left
-     * @param right
-     */
     public ComparisonExpression(Expression left, Expression right)
     {
         super(left, right);
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/ConstantExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/ConstantExpression.java
index 20c9f1438a..978ad3af7d 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/ConstantExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/ConstantExpression.java
@@ -181,8 +181,8 @@ public class ConstantExpression implements Expression
      * Encodes the value of string so that it looks like it would look like
      * when it was provided in a selector.
      *
-     * @param s
-     * @return
+     * @param s string to encode
+     * @return encoded string
      */
     public static String encodeString(String s)
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/Expression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/Expression.java
index 1030c7b588..64630c142e 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/Expression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/Expression.java
@@ -27,6 +27,7 @@ public interface Expression
 {
 
     /**
+     * @param message message to evaluate
      * @return the value of this expression
      */
     public Object evaluate(FilterableMessage message);
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/filter/LogicExpression.java b/qpid/java/common/src/main/java/org/apache/qpid/filter/LogicExpression.java
index f8ec19d23b..6de3a03ee0 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/filter/LogicExpression.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/filter/LogicExpression.java
@@ -36,10 +36,6 @@ public abstract class LogicExpression extends BinaryExpression implements Boolea
         return new AndExpression(lvalue, rvalue);
     }
 
-    /**
-     * @param left
-     * @param right
-     */
     public LogicExpression(BooleanExpression left, BooleanExpression right)
     {
         super(left, right);
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQMethodBodyImpl.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQMethodBodyImpl.java
index 571570d7b4..b1e8a73a0d 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQMethodBodyImpl.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQMethodBodyImpl.java
@@ -46,7 +46,9 @@ public abstract class AMQMethodBodyImpl implements AMQMethodBody
     }
 
 
-    /** unsigned short */
+    /** unsigned short
+     *
+     * @return body size*/
     abstract protected int getBodySize();
 
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQTypedValue.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQTypedValue.java
index 42a82eccba..e60ead7ad1 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQTypedValue.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/AMQTypedValue.java
@@ -33,15 +33,6 @@ import java.util.Map;
  * value. It provides the ability to read and write fully typed parameters to and from byte buffers. It also provides
  * the ability to create such parameters from Java native value and a type tag or to extract the native value and type
  * from one.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Create a fully typed AMQP value from a native type and a type tag. <td> {@link AMQType}
- * <tr><td> Create a fully typed AMQP value from a binary representation in a byte buffer. <td> {@link AMQType}
- * <tr><td> Write a fully typed AMQP value to a binary representation in a byte buffer. <td> {@link AMQType}
- * <tr><td> Extract the type from a fully typed AMQP value.
- * <tr><td> Extract the value from a fully typed AMQP value.
- * </table>
  */
 public abstract class AMQTypedValue
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/ContentHeaderBody.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/ContentHeaderBody.java
index 131d796af4..f2a443d5fd 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/ContentHeaderBody.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/ContentHeaderBody.java
@@ -76,11 +76,14 @@ public class ContentHeaderBody implements AMQBody
     }
 
     /**
-     * Helper method that is used currently by the persistence layer (by BDB at the moment).
-     * @param buffer
-     * @param size
-     * @return
-     * @throws AMQFrameDecodingException
+     * Helper method that is used currently by the persistence layer.
+     * @param buffer buffer to decode
+     * @param size size of the body
+     *
+     * @return the decoded header body
+     * @throws AMQFrameDecodingException if there is a decoding issue
+     * @throws AMQProtocolVersionException if there is a version issue
+     * @throws IOException if there is an IO issue
      */
     public static ContentHeaderBody createFromBuffer(DataInputStream buffer, long size)
         throws AMQFrameDecodingException, AMQProtocolVersionException, IOException
@@ -152,7 +155,9 @@ public class ContentHeaderBody implements AMQBody
         return weight;
     }
 
-    /** unsigned long but java can't handle that anyway when allocating byte array */
+    /** unsigned long but java can't handle that anyway when allocating byte array
+     *
+     * @return the body size */
     public long getBodySize()
     {
         return bodySize;
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/EncodingUtils.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/EncodingUtils.java
index 1ecd8a13b7..f0dcad4916 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/EncodingUtils.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/EncodingUtils.java
@@ -594,9 +594,9 @@ public class EncodingUtils
 
     /**
      * This is used for writing longstrs.
-     *
-     * @param buffer
-     * @param data
+     * @param buffer buffer to write to
+     * @param data data to write
+     * @throws IOException if there is an issue writing the output
      */
     public static void writeLongstr(DataOutput buffer, byte[] data) throws IOException
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/FieldTable.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/FieldTable.java
index 588f33d755..c4220894a8 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/FieldTable.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/FieldTable.java
@@ -73,7 +73,8 @@ public class FieldTable
      * Construct a new field table.
      *
      * @param buffer the buffer from which to read data. The length byte must be read already
-     * @param length the length of the field table. Must be > 0.
+     * @param length the length of the field table. Must be great than 0.
+     * @throws IOException if there is an issue reading the buffer
      */
     public FieldTable(DataInput buffer, long length) throws IOException
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/framing/ProtocolInitiation.java b/qpid/java/common/src/main/java/org/apache/qpid/framing/ProtocolInitiation.java
index 0a06f0f1e9..0bb72aa88f 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/framing/ProtocolInitiation.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/framing/ProtocolInitiation.java
@@ -137,6 +137,7 @@ public class ProtocolInitiation extends AMQDataBlock implements EncodableAMQData
          * @param in input buffer
          * @return true if we have enough data to decode the PI frame fully, false if more
          * data is required
+         * @throws IOException if there is an issue reading the input
          */
         public boolean decodable(MarkableDataInput in) throws IOException
         {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/Connection.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/Connection.java
index 3547205df1..7c604e8e8e 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/Connection.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/Connection.java
@@ -54,7 +54,7 @@ import java.util.concurrent.atomic.AtomicBoolean;
  *
  * @author Rafael H. Schloming
  *
- * @todo the channels map should probably be replaced with something
+ * TODO the channels map should probably be replaced with something
  * more efficient, e.g. an array or a map implementation that can use
  * short instead of Short
  */
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/ConnectionSettings.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/ConnectionSettings.java
index 2ff08fd751..d410e19a24 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/ConnectionSettings.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/ConnectionSettings.java
@@ -109,6 +109,7 @@ public class ConnectionSettings
      * Gets the heartbeat interval (seconds) for 0-8/9/9-1 protocols.
      * 0 means heartbeating is disabled.
      * null means use the broker-supplied value.
+     * @return the heartbeat interval
      */
     public Integer getHeartbeatInterval08()
     {
@@ -129,6 +130,7 @@ public class ConnectionSettings
     /**
      * Gets the heartbeat interval (seconds) for the 0-10 protocol.
      * 0 means heartbeating is disabled.
+     * @return the heartbeat interval
      */
     public int getHeartbeatInterval010()
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/Session.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/Session.java
index 8b29d6e424..90288eedcc 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/Session.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/Session.java
@@ -1206,6 +1206,7 @@ public class Session extends SessionInvoker
 
     /**
      * An auxiliary method for test purposes only
+     * @return true if flow is blocked
      */
     public boolean isFlowBlocked()
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Decoder.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Decoder.java
index fb3f91a3ce..6c027adcad 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Decoder.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Decoder.java
@@ -82,7 +82,7 @@ public interface Decoder
 	 * The uuid type encodes a universally unique id as defined by RFC-4122. 
 	 * The format and operations for this type can be found in section 4.1.2 of RFC-4122.
 	 * 
-	 * return a universally unique id as defined by RFC-4122.
+	 * @return a universally unique id as defined by RFC-4122.
 	 */    
     UUID readUuid();
 
@@ -114,14 +114,14 @@ public interface Decoder
 	 * Note that the encoded size refers to the number of octets of unicode, not necessarily the number of unicode 
 	 * characters since the UTF-8 unicode may include multi-byte character sequences.
 	 * 
-	 * return a string.
+	 * @return a string.
 	 */
     String readStr16();
 
 	/**
 	 * The vbin8 type encodes up to 255 octets of opaque binary data. 
 	 * 
-	 * return a byte array.
+	 * @return a byte array.
 	 */
     byte[] readVbin8();
     
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Encoder.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Encoder.java
index 5a3cec5616..a9eea13104 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Encoder.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/codec/Encoder.java
@@ -60,7 +60,7 @@ public interface Encoder
 	/**
 	 * The uint64 type is a 64-bit unsigned integral value encoded in network byte order.
 	 * 
-	 * @param b the unsigned integer to be encoded.
+	 * @param l the unsigned integer to be encoded.
 	 */    
     void writeUint64(long l);
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/transport/network/NetworkConnection.java b/qpid/java/common/src/main/java/org/apache/qpid/transport/network/NetworkConnection.java
index 1b8bbebdf5..2810e7a9e1 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/transport/network/NetworkConnection.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/transport/network/NetworkConnection.java
@@ -34,12 +34,12 @@ public interface NetworkConnection
     void close();
 
     /**
-     * Returns the remote address of the underlying socket.
+     * @return the remote address of the underlying socket.
      */
     SocketAddress getRemoteAddress();
 
     /**
-     * Returns the local address of the underlying socket.
+     * @return the local address of the underlying socket.
      */
     SocketAddress getLocalAddress();
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/typedmessage/TypedBytesContentReader.java b/qpid/java/common/src/main/java/org/apache/qpid/typedmessage/TypedBytesContentReader.java
index 0ba865f1e6..674a0e9468 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/typedmessage/TypedBytesContentReader.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/typedmessage/TypedBytesContentReader.java
@@ -54,7 +54,7 @@ public class TypedBytesContentReader implements TypedBytesCodes
      * Check that there is at least a certain number of bytes available to read
      *
      * @param len the number of bytes
-     * @throws javax.jms.MessageEOFException if there are less than len bytes available to read
+     * @throws EOFException if there are less than len bytes available to read
      */
     public void checkAvailable(int len) throws EOFException
     {
@@ -183,7 +183,8 @@ public class TypedBytesContentReader implements TypedBytesCodes
      * Note that this method reads a unicode character as two bytes from the stream
      *
      * @return the character read from the stream
-     * @throws javax.jms.JMSException
+     * @throws EOFException if there are less than the required bytes available to read
+     * @throws TypedBytesFormatException if the current write type is not compatible
      */
     public char readChar() throws EOFException, TypedBytesFormatException
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/util/CommandLineParser.java b/qpid/java/common/src/main/java/org/apache/qpid/util/CommandLineParser.java
index 3d17bbf6ea..0482ac7878 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/util/CommandLineParser.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/util/CommandLineParser.java
@@ -31,13 +31,13 @@ import java.util.regex.Pattern;
 
 /**
  * CommandLineParser provides a utility for specifying the format of a command line and parsing command lines to ensure
- * that they fit their specified format. A command line is made up of flags and options, both may be refered to as
+ * that they fit their specified format. A command line is made up of flags and options, both may be referred to as
  * options. A flag is an option that does not take an argument (specifying it means it has the value 'true' and not
  * specifying it means it has the value 'false'). Options must take arguments but they can be set up with defaults so
- * that they take a default value when not set. Options may be mandatory in wich case it is an error not to specify
+ * that they take a default value when not set. Options may be mandatory in which case it is an error not to specify
  * them on the command line. Flags are never mandatory because they are implicitly set to false when not specified.
  *
- * <p/>Some example command lines are:
+ * <p>Some example command lines are:
  *
  * <ul>
  * <li>This one has two options that expect arguments:
@@ -52,14 +52,15 @@ import java.util.regex.Pattern;
  * <pre>
  * jar -tvf mytar.tar
  * </pre>
+ * </ul>
  *
- * <p/>The parsing rules are:
+ * <p>The parsing rules are:
  *
  * <ol>
  * <li>Flags may be combined after a single '-' because they never take arguments. Normally such flags are single letter
  * flags but this is only a convention and not enforced. Flags of more than one letter are usually specified on their own.
  * <li>Options expecting arguments must always be on their own.
- * <li>The argument to an option may be seperated from it by whitespace or appended directly onto the option.
+ * <li>The argument to an option may be separated from it by whitespace or appended directly onto the option.
  * <li>The argument to an option may never begin with a '-' character.
  * <li>All other arguments not beginning with a '-' character are free arguments that do not belong to any option.
  * <li>The second or later of a set of duplicate or repeated flags are ignored.
@@ -70,18 +71,8 @@ import java.util.regex.Pattern;
  * the "bar" argument.
  * </ol>
  *
- * <p/>By default, unknown options are simply ignored if specified on the command line. This behaviour may be changed
+ * <p>By default, unknown options are simply ignored if specified on the command line. This behaviour may be changed
  * so that the parser reports all unknowns as errors by using the {@link #setErrorsOnUnknowns} method.
- *
- * <p><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Accept a command line specification.
- * <tr><td> Parse a command line into properties, validating it against its specification.
- * <tr><td> Report all errors between a command line and its specification.
- * <tr><td> Provide a formatted usage string for a command line.
- * <tr><td> Provide a formatted options in force string for a command line.
- * <tr><td> Allow errors on unknowns behaviour to be turned on or off.
- * </table>
  */
 public class CommandLineParser
 {
@@ -106,7 +97,7 @@ public class CommandLineParser
      * array may therefore easily be used to configure the command line parser in a single method call with an easily
      * readable format.
      *
-     * <p/>Each array of strings must be 2, 3, 4 or 5 elements long. If any of the last three elements are missing they
+     * <p>Each array of strings must be 2, 3, 4 or 5 elements long. If any of the last three elements are missing they
      * are assumed to be null. The elements specify the following parameters:
      * <ol>
      * <li>The name of the option without the leading '-'. For example, "file".  To specify the format of the 'free'
@@ -121,7 +112,7 @@ public class CommandLineParser
      *     this is ignored for flags.
      * <li>A regular expression describing the format that the argument must take. Ignored if null.
      * </ol>
-     * <p/>An example call to this constructor is:
+     * <p>An example call to this constructor is:
      *
      * <pre>
      * CommandLineParser commandLine = new CommandLineParser(
@@ -234,7 +225,7 @@ public class CommandLineParser
      * Parses a set of command line arguments into a set of properties, keyed by the argument flag. The free arguments
      * are keyed by integers as strings starting at "1" and then "2", ... and so on.
      *
-     * <p/>See the class level comment for a description of the parsing rules.
+     * <p>See the class level comment for a description of the parsing rules.
      *
      * @param args The command line arguments.
      *
@@ -488,6 +479,7 @@ public class CommandLineParser
 
     /**
      * If a command line has been parsed, calling this method sets all of its parsed options into the specified properties.
+     * @param properties properties
      */
     public void addCommandLineToProperties(Properties properties)
     {
@@ -508,7 +500,7 @@ public class CommandLineParser
      * to be called to use this parser a second time which is not likely seeing as a command line is usually only
      * specified once. However, it is exposed as a public method for the rare case where this may be done.
      *
-     * <p/>Cleans the internal state of this parser, removing all stored errors and information about the options in
+     * <p>Cleans the internal state of this parser, removing all stored errors and information about the options in
      * force.
      */
     public void reset()
@@ -643,11 +635,6 @@ public class CommandLineParser
      * Holds information about a command line options. This includes what its name is, whether or not it is a flag,
      * whether or not it is mandatory, what its user comment is, what its argument reminder text is and what its
      * regular expression format is.
-     *
-     * <p><table id="crc"><caption>CRC Card</caption>
-     * <tr><th> Responsibilities <th> Collaborations
-     * <tr><td> Hold details of a command line option.
-     * </table>
      */
     protected static class CommandLineOption
     {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/util/FileUtils.java b/qpid/java/common/src/main/java/org/apache/qpid/util/FileUtils.java
index f48103c650..dd347b54eb 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/util/FileUtils.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/util/FileUtils.java
@@ -37,12 +37,6 @@ import java.util.List;
  * FileUtils provides some simple helper methods for working with files. It follows the convention of wrapping all
  * checked exceptions as runtimes, so code using these methods is free of try-catch blocks but does not expect to
  * recover from errors.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Read a text file as a string.
- * <tr><td> Open a file or default resource as an input stream.
- * </table>
  */
 public class FileUtils
 {
@@ -214,7 +208,7 @@ public class FileUtils
      *
      * @param src The source file name.
      * @param dst The destination file name.
-     * @throws IOException
+     * @throws IOException if there is an issue copying the file
      */
     public static void copyCheckedEx(File src, File dst) throws IOException
     {
@@ -228,7 +222,7 @@ public class FileUtils
      *
      * @param in The InputStream
      * @param dst The destination file name.
-     * @throws IOException
+     * @throws IOException if there is an issue copying the stream
      */
     public static void copy(InputStream in, File dst) throws IOException
     {
@@ -383,7 +377,7 @@ public class FileUtils
      * @param file the file to search
      * @param search the search String
      *
-     * @throws java.io.IOException
+     * @throws java.io.IOException if there is an issue searching the file
      * @return the list of matching entries
      */
     public static List<String> searchFile(File file, String search)