Add some javadocs

transport/src/main/java/io/netty/channel/Channel.java

@@ -164,7 +164,7 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
      *         {@code null} if this channel is not connected.
      *         If this channel is not connected but it can receive messages
      *         from arbitrary remote addresses (e.g. {@link DatagramChannel},
-     *         use {@link MessageEvent#getRemoteAddress()} to determine
+     *         use {@link io.netty.channel.socket.DatagramPacket#remoteAddress()} to determine
      *         the origination of the received message as this method will
      *         return {@code null}.
      */
@@ -277,6 +277,11 @@ public interface Channel extends AttributeMap, ChannelOutboundInvoker, ChannelPr
          */
         void resumeRead();
 
+        /**
+         * Send a {@link FileRegion} to the remote peer and notify the {@link ChannelFuture} once it completes
+         * or an error was detected. Once the {@link FileRegion} was transfered or an error was thrown it will
+         * automaticly closed via {@link io.netty.channel.FileRegion#close()}.
+         */
         void sendFile(FileRegion region, ChannelFuture future);
     }
 }

transport/src/main/java/io/netty/channel/ChannelOutboundInvoker.java

@@ -18,23 +18,147 @@ package io.netty.channel;
 import java.net.SocketAddress;
 
 public interface ChannelOutboundInvoker {
+    /**
+     * Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of an error.
+     */
     ChannelFuture bind(SocketAddress localAddress);
+
+    /**
+     * Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     */
     ChannelFuture connect(SocketAddress remoteAddress);
+
+    /**
+     * Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of
+     * an error.
+     */
     ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress);
+
+    /**
+     * Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     */
     ChannelFuture disconnect();
+
+    /**
+     * Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     *
+     * After it is closed it is not possible to reuse it again.
+     */
     ChannelFuture close();
+
+    /**
+     * Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
+     * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
+     * an error.
+     *
+     */
     ChannelFuture deregister();
+
+    /**
+     * Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     */
     ChannelFuture flush();
+
+    /**
+     * Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     *
+     * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
+     */
     ChannelFuture write(Object message);
+
+    /**
+     * Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     */
     ChannelFuture sendFile(FileRegion region);
 
+    /**
+     * Bind to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture bind(SocketAddress localAddress, ChannelFuture future);
+
+    /**
+     * Connect to the given {@link SocketAddress} and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture connect(SocketAddress remoteAddress, ChannelFuture future);
+
+    /**
+     * Connect to the given {@link SocketAddress} while bind to the localAddress and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of
+     * an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture connect(SocketAddress remoteAddress, SocketAddress localAddress, ChannelFuture future);
+
+    /**
+     * Discconect from the remote peer and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture disconnect(ChannelFuture future);
+
+    /**
+     * Close this ChannelOutboundInvoker and notify the {@link ChannelFuture} once the operation completes,
+     * either because the operation was successful or because of
+     * an error.
+     *
+     * After it is closed it is not possible to reuse it again.
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture close(ChannelFuture future);
+
+    /**
+     * Deregister this ChannelOutboundInvoker from the previous assigned {@link EventExecutor} and notify the
+     * {@link ChannelFuture} once the operation completes, either because the operation was successful or because of
+     * an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture deregister(ChannelFuture future);
+
+    /**
+     * Flush all pending data which belongs to this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture flush(ChannelFuture future);
+
+    /**
+     * Write a message via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     *
+     * If you want to write a {@link FileRegion} use {@link #sendFile(FileRegion)}
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture write(Object message, ChannelFuture future);
+
+
+    /**
+     * Send a {@link FileRegion} via this ChannelOutboundInvoker and notify the {@link ChannelFuture}
+     * once the operation completes, either because the operation was successful or because of an error.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture sendFile(FileRegion region, ChannelFuture future);
 }

transport/src/main/java/io/netty/channel/socket/DatagramChannel.java

@@ -23,7 +23,7 @@ import java.net.InetSocketAddress;
 import java.net.NetworkInterface;
 
 /**
- * A UDP/IP {@link Channel} which is created by {@link DatagramChannelFactory}.
+ * A UDP/IP {@link Channel}}.
  * @apiviz.landmark
  * @apiviz.composedOf io.netty.channel.socket.DatagramChannelConfig
  */
@@ -35,70 +35,131 @@ public interface DatagramChannel extends Channel {
     @Override
     InetSocketAddress remoteAddress();
 
+    /**
+     * Return {@code true} if the {@link DatagramChannel} is connected to the remote peer.
+     */
     boolean isConnected();
 
     /**
-     * Joins a multicast group.
+     * Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes.
      */
     ChannelFuture joinGroup(InetAddress multicastAddress);
+
+    /**
+     * Joins a multicast group and notifies the {@link ChannelFuture} once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture joinGroup(InetAddress multicastAddress, ChannelFuture future);
 
     /**
-     * Joins the specified multicast group at the specified interface.
+     * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
+     * once the operation completes.
      */
     ChannelFuture joinGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface);
+
+    /**
+     * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
+     * once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture joinGroup(
             InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future);
 
+    /**
+     * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
+     * once the operation completes.
+     */
     ChannelFuture joinGroup(InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
+
+    /**
+     * Joins the specified multicast group at the specified interface and notifies the {@link ChannelFuture}
+     * once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture joinGroup(
             InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source, ChannelFuture future);
 
     /**
-     * Leaves a multicast group.
+     * Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes.
      */
     ChannelFuture leaveGroup(InetAddress multicastAddress);
+
+    /**
+     * Leaves a multicast group and notifies the {@link ChannelFuture} once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture leaveGroup(InetAddress multicastAddress, ChannelFuture future);
 
     /**
-     * Leaves a multicast group on a specified local interface.
+     * Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the
+     * operation completes.
      */
     ChannelFuture leaveGroup(InetSocketAddress multicastAddress, NetworkInterface networkInterface);
+
+    /**
+     * Leaves a multicast group on a specified local interface and notifies the {@link ChannelFuture} once the
+     * operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture leaveGroup(
             InetSocketAddress multicastAddress, NetworkInterface networkInterface, ChannelFuture future);
 
     /**
-     * Leave the specified multicast group at the specified interface using the specified source.
+     * Leave the specified multicast group at the specified interface using the specified source and notifies
+     * the {@link ChannelFuture} once the operation completes.
+     *
      */
     ChannelFuture leaveGroup(
             InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source);
+
+    /**
+     * Leave the specified multicast group at the specified interface using the specified source and notifies
+     * the {@link ChannelFuture} once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
+     */
     ChannelFuture leaveGroup(
             InetAddress multicastAddress, NetworkInterface networkInterface, InetAddress source,
             ChannelFuture future);
 
-        /**
+    /**
-     * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface
+     * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies
+     * the {@link ChannelFuture} once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture block(
             InetAddress multicastAddress, NetworkInterface networkInterface,
             InetAddress sourceToBlock);
 
     /**
-     * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface
+     * Block the given sourceToBlock address for the given multicastAddress on the given networkInterface and notifies
+     * the {@link ChannelFuture} once the operation completes.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture block(
             InetAddress multicastAddress, NetworkInterface networkInterface,
             InetAddress sourceToBlock, ChannelFuture future);
 
     /**
-     * Block the given sourceToBlock address for the given multicastAddress
+     * Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once
+     * the operation completes.
      *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture block(InetAddress multicastAddress, InetAddress sourceToBlock);
 
     /**
-     * Block the given sourceToBlock address for the given multicastAddress
+     * Block the given sourceToBlock address for the given multicastAddress and notifies the {@link ChannelFuture} once
+     * the operation completes.
      *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture block(
             InetAddress multicastAddress, InetAddress sourceToBlock, ChannelFuture future);

transport/src/main/java/io/netty/channel/socket/DatagramPacket.java

@@ -19,6 +19,9 @@ import io.netty.buffer.ByteBuf;
 
 import java.net.InetSocketAddress;
 
+/**
+ * The message container that is used for {@link DatagramChannel} to communicate with the remote peer.
+ */
 public class DatagramPacket {
 
     private final ByteBuf data;
@@ -36,10 +39,17 @@ public class DatagramPacket {
         this.remoteAddress = remoteAddress;
     }
 
+    /**
+     * Return the data which is container. May return an empty {@link ByteBuf}
+     */
     public ByteBuf data() {
         return data;
     }
 
+    /**
+     * The {@link InetSocketAddress} which this {@link DatagramPacket} will send to or was received from.
+     * If {@code null} is used the default address will be used which the {@link DatagramChannel} was connected to.
+     */
     public InetSocketAddress remoteAddress() {
         return remoteAddress;
     }

transport/src/main/java/io/netty/channel/socket/InternetProtocolFamily.java

@@ -16,7 +16,7 @@
 package io.netty.channel.socket;
 
 /**
- * Internet Protocol (IP) families
+ * Internet Protocol (IP) families used byte the {@link DatagramChannel}
  */
 public enum InternetProtocolFamily {
     IPv4,

transport/src/main/java/io/netty/channel/socket/SctpChannel.java

@@ -85,6 +85,8 @@ public interface SctpChannel extends Channel {
     /**
      * Bind a address to the already bound channel to enable multi-homing.
      * The Channel bust be bound and yet to be connected.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture bindAddress(InetAddress localAddress, ChannelFuture future);
 
@@ -97,6 +99,8 @@ public interface SctpChannel extends Channel {
     /**
      *  Unbind the address from channel's multi-homing address list.
      *  The address should be added already in multi-homing address list.
+     *
+     * The given {@link ChannelFuture} will be notified and also returned.
      */
     ChannelFuture unbindAddress(InetAddress localAddress, ChannelFuture future);
 }

transport/src/main/java/io/netty/channel/socket/SctpMessage.java

@@ -28,8 +28,7 @@ public final class SctpMessage {
     private final int protocolIdentifier;
 
     private final ByteBuf payloadBuffer;
-
+    private final MessageInfo msgInfo;
-    private MessageInfo msgInfo;
 
     /**
      * Essential data that is being carried within SCTP Data Chunk
@@ -41,6 +40,7 @@ public final class SctpMessage {
         this.protocolIdentifier = protocolIdentifier;
         this.streamIdentifier = streamIdentifier;
         this.payloadBuffer = payloadBuffer;
+        this.msgInfo = null;
     }
 
     public SctpMessage(MessageInfo msgInfo, ByteBuf payloadBuffer) {

transport/src/main/java/io/netty/channel/socket/SocketChannel.java

@@ -54,6 +54,8 @@ public interface SocketChannel extends Channel {
 
     /**
      * @see Socket#shutdownOutput()
+     *
+     * Will notify and return the given {@link ChannelFuture}
      */
     ChannelFuture shutdownOutput(ChannelFuture future);
 }