Javadoc cleanup

src/org/jgroups/Address.java

@@ -2,13 +2,19 @@
 package org.jgroups;
 
 import org.jgroups.util.Streamable;
-
-
+import org.jgroups.util.UUID;
 
 /**
- * Abstract address. Used to identify members on a group to send messages to.
- * Addresses are mostly generated by the bottom-most (transport) layers (e.g. UDP, TCP, LOOPBACK).
+ * Address identifies cluster member. For example, whenever a unicast message is sent in a cluster
+ * an Address of a cluster member message recipient needs to be specified. Similarly a cluster
+ * member can use Address to check its own identity, request a state from a particular member and so
+ * on. Addresses are mostly generated by the bottom-most (transport) layers (e.g. UDP, TCP,
+ * LOOPBACK).
+ * 
  * @author Bela Ban
+ * @since 2.0
+ * @see PhysicalAddress
+ * @see UUID
  */
 public interface Address extends Streamable, Comparable<Address>, Cloneable {
     // flags used for marshalling

src/org/jgroups/ChannelListener.java

@@ -1,13 +1,43 @@
-
 package org.jgroups;
 
-
 /**
- * Allows a listener to be notified when important channel events occur. For example, when
- * a channel is closed, a PullPushAdapter can be notified, and stop accordingly.
+ * Allows a listener to be notified when an important channel lifecycle event occurs.
+ * <p>
+ * 
+ * Usually clients do not need to implement ChannelListener interface. However, this interface can
+ * useful in scenarios when an application opens multiple channels and needs to tracks major
+ * lifecycle events on those channels from a single location or in scenarios when channel is wrapped
+ * by JGroups building block installed on top of a channel (RpcDispatcher etc) while a client needs
+ * to be notified about major channel lifecycle events.
+ * 
+ * @see Channel#addChannelListener(ChannelListener)
+ * @see Channel#removeChannelListener(ChannelListener)
+ * @see Channel#clearChannelListeners()
+ * 
+ * @author Bela Ban
+ * @since 2.0
+ * 
  */
 public interface ChannelListener {
-    void channelConnected(Channel channel);
-    void channelDisconnected(Channel channel);
-    void channelClosed(Channel channel);
+
+   /**
+    * Channel has been connected notification callback
+    * 
+    * @param channel the channel that has been connected
+    */
+   void channelConnected(Channel channel);
+
+   /**
+    * Channel has been disconnected notification callback
+    * 
+    * @param channel the disconnected channel
+    */
+   void channelDisconnected(Channel channel);
+
+   /**
+    * Channel has been closed notification callback
+    * 
+    * @param channel the closed channel
+    */
+   void channelClosed(Channel channel);
 }

src/org/jgroups/Event.java

@@ -1,9 +1,9 @@
 package org.jgroups;
 
-
-
 /**
- * Used for inter-stack and intra-stack communication.
+ * Event is a JGroups internal class used for inter-stack and intra-stack communication. 
+ * 
+ * @since 2.0
  * @author Bela Ban
  */
 public class Event {

src/org/jgroups/Global.java

@@ -4,9 +4,10 @@
 import org.jgroups.protocols.SCOPE;
 
 /**
- * Globals used by JGroups packages.
+ * Global is a JGroups internal class defining global variables.
  * 
- * @author Bela Ban Mar 29, 2004
+ * @since 2.0
+ * @author Bela Ban 
  */
 public class Global {
     public static final int BYTE_SIZE   = Byte.SIZE    / 8; // 1

src/org/jgroups/Header.java

@@ -3,10 +3,12 @@
 
 import org.jgroups.util.Streamable;
 
-
 /**
- * Abstract base class for all headers to be added to a Message.
+ * Header is a JGroups internal base class for all JGroups headers. Client normally do not need to
+ * interact with headers unless they are developing their custom protocols.
+ * 
  * @author Bela Ban
+ * @since 2.0
  */
 public abstract class Header implements Streamable {
 

src/org/jgroups/JChannel.java

@@ -24,14 +24,15 @@
 import java.util.concurrent.Callable;
 import java.util.concurrent.ConcurrentMap;
 
-
 /**
- * JChannel is a pure Java implementation of Channel.<p/>
- * When a JChannel object is instantiated it automatically builds the associated protocol stack.<p/>
- * The configuration of a JChannel is done via XML, e.g. udp.xml inside the JGroups JAR. This file lists all the
- * protocols to be used, and for each protocol, its properties (e.g. fragmentation size for the fragmentation
- * protocol).
+ * JChannel is a default implementation of a Channel abstraction.
+ * <p/>
+ * 
+ * JChannel is instantiated using an appropriate form of a protocol stack description. Protocol
+ * stack can be described using a file, URL or a stream containing XML stack description.
+ * 
  * @author Bela Ban
+ * @since 2.0
  */
 @MBean(description="JGroups channel")
 public class JChannel extends Channel {
@@ -148,8 +149,8 @@ public JChannel(String props) throws Exception {
     }
 
     /**
-     * Creates a channel with a configurtation based on an input stream.
-     * @param input An input stream, pointing to a streamed configurtaion
+     * Creates a channel with a configuration based on an input stream.
+     * @param input An input stream, pointing to a streamed configuration
      * @throws Exception
      */
     public JChannel(InputStream input) throws Exception {
@@ -171,7 +172,7 @@ public JChannel(ProtocolStackConfigurator configurator) throws Exception {
 
     /**
      * Creates a channel with the same configuration as the channel passed to this constructor. This is used by
-     * testing code, and should not be used by any other code !
+     * testing code, and should not be used by clients !
      * @param ch
      * @throws Exception
      */