QPID-5980: more javadoc fixups

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

11 files changed, 30 insertions, 76 deletions

diff --git a/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java b/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java
index c0427c2f37..fff62424ca 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/api/Message.java
@@ -47,6 +47,7 @@ public interface Message
 	 * <li> To Socket (Stream)
 	 * </ul>
 	 * @param src - the data to append
+	 * @throws IOException if there is an issue appending the data
 	 */
 	public void appendData(byte[] src) throws IOException;
 
@@ -63,6 +64,7 @@ public interface Message
      * <li> To Socket (Stream)
      * </ul>
      * @param src - the data to append
+     * @throws IOException if there is an issue appending the data
      */
     public void appendData(ByteBuffer src) throws IOException;
 
@@ -78,6 +80,7 @@ public interface Message
 	 * <li> From Socket as and when it gets streamed
 	 * </ul>
 	 * @param target  The target byte[] which the data gets copied to
+     * @throws IOException if there is an issue reading the data
 	 */
     public void readData(byte[] target) throws IOException;
 
@@ -94,7 +97,7 @@ public interface Message
      * </ul>
      *
      * @return A ByteBuffer containing data
-     * @throws IOException
+     * @throws IOException if there is an issue reading the data
      */
     public ByteBuffer readData() throws IOException;
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java b/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java
index f50e65214c..483fbaea50 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/common/AMQPFilterTypes.java
@@ -24,11 +24,6 @@ import org.apache.qpid.framing.AMQShortString;
 
 /**
  * Specifies the different filter types for consumers that filter their messages.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Represent different consumer filter types.
- * </table>
  */
 public enum AMQPFilterTypes
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java b/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java
index 2c783aeaa4..25baf86fe6 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/common/QpidProperties.java
@@ -35,17 +35,13 @@ import java.util.Properties;
  * idea behind this, is that every build has these values incorporated directly into its jar file, so that code in the
  * wild can be identified, should its origination be forgotten.
  *
- * <p/>To get the build version of any Qpid code call the {@link #main} method. This version string is usually also
+ * <p>To get the build version of any Qpid code call the {@link #main} method. This version string is usually also
  * printed to the console on broker start up.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><td>Load build versioning information into the runtime, for code identification purposes.
- * </table>
- *
- * @todo Code to locate/load/log properties can be factored into a reusable properties utils class. Avoid having this
+ * <p>
+ * TODO  Code to locate/load/log properties can be factored into a reusable properties utils class. Avoid having this
  *       same snippet of loading code scattered in many places.
- *
- * @todo Could also add a build number property for a sequential build number assigned by an automated build system, for
+ * <p>
+ * TODO  Could also add a build number property for a sequential build number assigned by an automated build system, for
  *       build reproducability purposes.
  */
 public class QpidProperties
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
index b8181e3b87..cf08dafb49 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyException.java
@@ -26,12 +26,8 @@ import org.apache.qpid.AMQException;
  * Indicates a failure to parse a property expansion. See {@link PropertyUtils} for the code that does property
  * expansions.
  *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaboration
- * <tr><td> Represent failure to expand a property name into a value.
- * </table>
- *
- * @todo Not an AMQP exception as no status code.
+ * <p>
+ * TODO Not an AMQP exception as no status code.
  */
 public class PropertyException extends AMQException
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java
index 81702ee1ea..da366ffd0f 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/configuration/PropertyUtils.java
@@ -26,15 +26,11 @@ import java.util.Iterator;
 /**
  * PropertyUtils provides helper methods for dealing with Java properties.
  *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Expand system properties into strings with named expansions.
- * </table>
- *
- * @todo Make the lookup method generic by passing in the properties to use for the expansion, rather than hard coding
+ * <p>
+ * TODO  Make the lookup method generic by passing in the properties to use for the expansion, rather than hard coding
  *       as system properties. The expansion code has greater potential for re-use that way.
- *
- * @todo Some more property related code could be added to this utils class, which might more appropriately reside under
+ * <p>
+ * TODO  Some more property related code could be added to this utils class, which might more appropriately reside under
  *       org.apache.qpid.util. For example standardised code to load properties from a resource name, currently found in
  *       QpidProperties and possibly other places could be moved here.
  */
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
index 2a2342ca14..5e39409382 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQConstant.java
@@ -28,20 +28,14 @@ import java.util.Map;
 /**
  * Defines constants for AMQP codes and also acts as a factory for creating such constants from the raw codes. Each
  * constant also defines a short human readable description of the constant.
- *
- * @todo Why would a constant be defined that is not in the map? Seems more natural that getConstant should raise an
+ * <p>
+ * TODO  Why would a constant be defined that is not in the map? Seems more natural that getConstant should raise an
  *       exception for an unknown constant. Or else provide an explanation of why this is so. Also, there is no way for
  *       callers to determine the unknown status of a code except by comparing its name to "unknown code", which would
  *       seem to render this scheme a little bit pointless?
- *
- * @todo Java has a nice enum construct for doing this sort of thing. Maybe this is done in the old style for Java 1.4
+ * <p>
+ * TODO  Java has a nice enum construct for doing this sort of thing. Maybe this is done in the old style for Java 1.4
  *       backward compatability? Now that is handled through retrotranslater it may be time to use enum.
- *
- * <p/><tabld id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Define the set of AMQP status codes.
- * <tr><td> Provide a factory to lookup constants by their code.
- * <tr><td>
  */
 public final class AMQConstant
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
index fd6907a152..9b38f7926b 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodEvent.java
@@ -25,19 +25,14 @@ import org.apache.qpid.framing.AMQMethodBody;
 /**
  * AMQMethodEvent encapsulates an AMQP method call, and the channel on which that method call occurred.
  *
- * <p/>Supplies the:
+ * <p>Supplies the:
  * <ul>
  * <li>channel id</li>
  * <li>protocol method</li>
  * </ul>
  *
- * <p/>As the event contains the context in which it occurred, event listeners do not need to be statefull.
+ * <p>As the event contains the context in which it occurred, event listeners do not need to be statefull.
  * to listeners. Events are often handled by {@link AMQMethodListener}s.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities <th> Collaborations
- * <tr><td> Encapsulate an AMQP method call and the channel as the context for the method call.
- * </table>
  */
 public class AMQMethodEvent<M extends AMQMethodBody>
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
index 8cc9709c9c..3e7c67493d 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQMethodListener.java
@@ -27,17 +27,11 @@ import org.apache.qpid.framing.AMQMethodBody;
  * AMQMethodListener is a listener that receives notifications of AMQP methods. The methods are packaged as events in
  * {@link AMQMethodEvent}.
  *
- * <p/>An event listener may be associated with a particular context, usually an AMQP channel, and in addition to
+ * <p>An event listener may be associated with a particular context, usually an AMQP channel, and in addition to
  * receiving method events will be notified of errors on that context. This enables listeners to perform any clean
  * up that they need to do before the context is closed or retried.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities
- * <tr><td> Accept notification of AMQP method events. <td> {@link AMQMethodEvent}
- * <tr><td> Accept notification of errors on the event context.
- * </table>
- *
- * @todo Document why the exception is passed to the error method. Is it so that the exception can be passed
+ * <p>
+ * TODO  Document why the exception is passed to the error method. Is it so that the exception can be passed
  *       from the event handling thread to another thread and rethown from there? It is unusual to pass exceptions as
  *       method arguments, because they have their own mechanism for propagating through the call stack, so some
  *       explanation ought to be provided.
@@ -49,14 +43,14 @@ public interface AMQMethodListener
      *
      * @param evt The AMQP method event (contains the method and channel).
      *
-     * @return <tt>true</tt> if the handler processes the method frame, <tt>false<tt> otherwise. Note that this does
+     * @return true if the handler processes the method frame, false otherwise. Note that this does
      *         not prohibit the method event being delivered to subsequent listeners but can be used to determine if
      *         nobody has dealt with an incoming method frame.
      *
-     * @throws Exception if an error has occurred. This exception may be delivered to all registered listeners using
+     * @throws AMQException if an error has occurred. This exception may be delivered to all registered listeners using
      *         the error() method (see below) allowing them to perform cleanup if necessary.
-     *
-     * @todo Consider narrowing the exception.
+     * <p>
+     * TODO Consider narrowing the exception.
      */
     <B extends AMQMethodBody> boolean methodReceived(AMQMethodEvent<B> evt) throws AMQException;
 
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
index 65884e4950..0a050becdc 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQProtocolWriter.java
@@ -26,11 +26,6 @@ import org.apache.qpid.framing.AMQDataBlock;
  * AMQProtocolWriter provides a method to write a frame of data 'to the wire', in the context of the object
  * that implements the method, usually some sort of session. The block of data, encapsulated by {@link AMQDataBlock},
  * will be encoded as it is written.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities
- * <tr><td> Write an encoded block of data to the write, in the context of a session.
- * </table>
  */
 public interface AMQProtocolWriter
 {
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
index 33604b05d9..0c643f6322 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/AMQVersionAwareProtocolSession.java
@@ -34,13 +34,8 @@ import java.nio.ByteBuffer;
 /**
  * AMQVersionAwareProtocolSession is implemented by all AMQP session classes, that need to provide an awareness to
  * callers of the version of the AMQP protocol that they are able to work with.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities
- * <tr><td> Provide the method registry for a specific version of the AMQP.
- * </table>
- *
- * @todo Why is this a seperate interface to {@link ProtocolVersionAware}, could they be combined into a single
+ * <p>
+ * TODO Why is this a seperate interface to {@link ProtocolVersionAware}, could they be combined into a single
  *       interface and one of them eliminated? Move getRegistry method to ProtocolVersionAware, make the sessions
  *       implement AMQProtocolWriter directly and drop this interface.
  */
diff --git a/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java b/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
index 56f950dd85..f12cd9af8e 100644
--- a/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
+++ b/qpid/java/common/src/main/java/org/apache/qpid/protocol/ProtocolVersionAware.java
@@ -25,11 +25,6 @@ import org.apache.qpid.framing.ProtocolVersion;
 /**
  * ProtocolVersionAware is implemented by all AMQP handling classes, that need to provide an awareness to callers of
  * the version of the AMQP protocol that they are able to handle.
- *
- * <p/><table id="crc"><caption>CRC Card</caption>
- * <tr><th> Responsibilities
- * <tr><td> Report the major and minor AMQP version handled.
- * </table>
  */
 public interface ProtocolVersionAware
 {