Convert javadoc to C# xmldoc in the DotNetty.Transport project (Azure…

…#389)

This is a progressive commit towards completing Azure#386.

No code changes have been made, only changes to comments.

These changes to comments include:
- Transforming {@link Symbol} occurrences to <see cref="Symbol"/>
- Updating Java example code in comments with C# equivalents
- Translating/removing comments that do not apply to .NET generally
- Removing Netty-specific comments that do not yet apply to this port
- Various grammar and typo corrections

src/DotNetty.Transport/Bootstrapping/AbstractBootstrap.cs

@@ -16,12 +16,11 @@ namespace DotNetty.Transport.Bootstrapping
     using DotNetty.Transport.Channels;
 
     /// <summary>
-    ///     {@link AbstractBootstrap} is a helper class that makes it easy to bootstrap a {@link Channel}. It support
-    ///     method-chaining to provide an easy way to configure the {@link AbstractBootstrap}.
-    ///     <p>
-    ///         When not used in a {@link ServerBootstrap} context, the {@link #bind()} methods are useful for connectionless
-    ///         transports such as datagram (UDP).
-    ///     </p>
+    /// This is a helper class that makes it easy to bootstrap an <see cref="IChannel"/>. It supports method-
+    /// chaining to provide an easy way to configure the <see cref="AbstractBootstrap{TBootstrap,TChannel}"/>.
+    /// 
+    /// When not used in a <see cref="ServerBootstrap"/> context, the <see cref="BindAsync(EndPoint)"/> methods
+    /// are useful for connectionless transports such as datagram (UDP).
     /// </summary>
     public abstract class AbstractBootstrap<TBootstrap, TChannel>
         where TBootstrap : AbstractBootstrap<TBootstrap, TChannel>
@@ -54,9 +53,10 @@ protected internal AbstractBootstrap(AbstractBootstrap<TBootstrap, TChannel> boo
         }
 
         /// <summary>
-        ///     The {@link EventLoopGroup} which is used to handle all the events for the to-be-created
-        ///     {@link Channel}
+        /// Specifies the <see cref="IEventLoopGroup"/> which will handle events for the <see cref="IChannel"/> being built.
         /// </summary>
+        /// <param name="group">The <see cref="IEventLoopGroup"/> which is used to handle all the events for the to-be-created <see cref="IChannel"/>.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public virtual TBootstrap Group(IEventLoopGroup group)
         {
             Contract.Requires(group != null);
@@ -70,12 +70,11 @@ public virtual TBootstrap Group(IEventLoopGroup group)
         }
 
         /// <summary>
-        ///     The {@link Class} which is used to create {@link Channel} instances from.
-        ///     You either use this or {@link #channelFactory(io.netty.channel.ChannelFactory)} if your
-        ///     {@link Channel} implementation has no no-args constructor.
+        /// Specifies the <see cref="Type"/> of <see cref="IChannel"/> which will be created.
         /// </summary>
-        public TBootstrap Channel<T>()
-            where T : TChannel, new() => this.ChannelFactory(() => new T());
+        /// <typeparam name="T">The <see cref="Type"/> which is used to create <see cref="IChannel"/> instances from.</typeparam>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
+        public TBootstrap Channel<T>() where T : TChannel, new() => this.ChannelFactory(() => new T());
 
         public TBootstrap ChannelFactory(Func<TChannel> channelFactory)
         {
@@ -85,33 +84,49 @@ public TBootstrap ChannelFactory(Func<TChannel> channelFactory)
         }
 
         /// <summary>
-        ///     The {@link SocketAddress} which is used to bind the local "end" to.
+        /// Assigns the <see cref="EndPoint"/> which is used to bind the local "end" to.
         /// </summary>
+        /// <param name="localAddress">The <see cref="EndPoint"/> instance to bind the local "end" to.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public TBootstrap LocalAddress(EndPoint localAddress)
         {
             this.localAddress = localAddress;
             return (TBootstrap)this;
         }
 
         /// <summary>
-        ///     @see {@link #localAddress(SocketAddress)}
+        /// Assigns the local <see cref="EndPoint"/> which is used to bind the local "end" to.
+        /// This overload binds to a <see cref="IPEndPoint"/> for any IP address on the local machine, given a specific port.
         /// </summary>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public TBootstrap LocalAddress(int inetPort) => this.LocalAddress(new IPEndPoint(IPAddress.Any, inetPort));
 
         /// <summary>
-        ///     @see {@link #localAddress(SocketAddress)}
+        /// Assigns the local <see cref="EndPoint"/> which is used to bind the local "end" to.
+        /// This overload binds to a <see cref="DnsEndPoint"/> for a given hostname and port.
         /// </summary>
+        /// <param name="inetHost">The hostname to bind the local "end" to.</param>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public TBootstrap LocalAddress(string inetHost, int inetPort) => this.LocalAddress(new DnsEndPoint(inetHost, inetPort));
 
         /// <summary>
-        ///     @see {@link #localAddress(SocketAddress)}
+        /// Assigns the local <see cref="EndPoint"/> which is used to bind the local "end" to.
+        /// This overload binds to a <see cref="IPEndPoint"/> for a given <see cref="IPAddress"/> and port.
         /// </summary>
+        /// <param name="inetHost">The <see cref="IPAddress"/> to bind the local "end" to.</param>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public TBootstrap LocalAddress(IPAddress inetHost, int inetPort) => this.LocalAddress(new IPEndPoint(inetHost, inetPort));
 
         /// <summary>
-        ///     Allow to specify a {@link ChannelOption} which is used for the {@link Channel} instances once they got
-        ///     created. Use a value of {@code null} to remove a previous set {@link ChannelOption}.
+        /// Allows the specification of a <see cref="ChannelOption{T}"/> which is used for the
+        /// <see cref="IChannel"/> instances once they get created. Use a value of <c>null</c> to remove
+        /// a previously set <see cref="ChannelOption{T}"/>.
         /// </summary>
+        /// <param name="option">The <see cref="ChannelOption{T}"/> to configure.</param>
+        /// <param name="value">The value to set the given option.</param>
         public TBootstrap Option<T>(ChannelOption<T> option, T value)
         {
             Contract.Requires(option != null);
@@ -129,8 +144,8 @@ public TBootstrap Option<T>(ChannelOption<T> option, T value)
         }
 
         /// <summary>
-        ///     Allow to specify an initial attribute of the newly created <see cref="IChannel" /> . If the <c>value</c> is
-        ///     <c>null</c>, the attribute of the specified <c>key</c> is removed.
+        /// Allows specification of an initial attribute of the newly created <see cref="IChannel" />. If the <c>value</c> is
+        /// <c>null</c>, the attribute of the specified <c>key</c> is removed.
         /// </summary>
         public TBootstrap Attribute<T>(AttributeKey<T> key, T value)
             where T : class
@@ -150,12 +165,7 @@ public TBootstrap Attribute<T>(AttributeKey<T> key, T value)
         }
 
         /// <summary>
-        ///     Allow to specify an initial attribute of the newly created {@link Channel}.  If the {@code value} is
-        ///     {@code null}, the attribute of the specified {@code key} is removed.
-        /// </summary>
-        /// <summary>
-        ///     Validate all the parameters. Sub-classes may override this, but should
-        ///     call the super method in that case.
+        /// Validates all the parameters. Sub-classes may override this, but should call the super method in that case.
         /// </summary>
         public virtual TBootstrap Validate()
         {
@@ -171,14 +181,14 @@ public virtual TBootstrap Validate()
         }
 
         /// <summary>
-        ///     Returns a deep clone of this bootstrap which has the identical configuration.  This method is useful when making
-        ///     multiple {@link Channel}s with similar settings.  Please note that this method does not clone the
-        ///     {@link EventLoopGroup} deeply but shallowly, making the group a shared resource.
+        /// Returns a deep clone of this bootstrap which has the identical configuration.  This method is useful when making
+        /// multiple <see cref="IChannel"/>s with similar settings.  Please note that this method does not clone the
+        /// <see cref="IEventLoopGroup"/> deeply but shallowly, making the group a shared resource.
         /// </summary>
         public abstract TBootstrap Clone();
 
         /// <summary>
-        ///     Create a new {@link Channel} and register it with an {@link EventLoop}.
+        /// Creates a new <see cref="IChannel"/> and registers it with an <see cref="IEventLoop"/>.
         /// </summary>
         public Task RegisterAsync()
         {
@@ -187,8 +197,9 @@ public Task RegisterAsync()
         }
 
         /// <summary>
-        ///     Create a new {@link Channel} and bind it.
+        /// Creates a new <see cref="IChannel"/> and binds it to the endpoint specified via the <see cref="LocalAddress(EndPoint)"/> methods.
         /// </summary>
+        /// <returns>The bound <see cref="IChannel"/>.</returns>
         public Task<IChannel> BindAsync()
         {
             this.Validate();
@@ -201,23 +212,36 @@ public Task<IChannel> BindAsync()
         }
 
         /// <summary>
-        ///     Create a new {@link Channel} and bind it.
+        /// Creates a new <see cref="IChannel"/> and binds it.
+        /// This overload binds to a <see cref="IPEndPoint"/> for any IP address on the local machine, given a specific port.
         /// </summary>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The bound <see cref="IChannel"/>.</returns>
         public Task<IChannel> BindAsync(int inetPort) => this.BindAsync(new IPEndPoint(IPAddress.Any, inetPort));
 
         /// <summary>
-        ///     Create a new {@link Channel} and bind it.
+        /// Creates a new <see cref="IChannel"/> and binds it.
+        /// This overload binds to a <see cref="DnsEndPoint"/> for a given hostname and port.
         /// </summary>
+        /// <param name="inetHost">The hostname to bind the local "end" to.</param>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The bound <see cref="IChannel"/>.</returns>
         public Task<IChannel> BindAsync(string inetHost, int inetPort) => this.BindAsync(new DnsEndPoint(inetHost, inetPort));
 
         /// <summary>
-        ///     Create a new {@link Channel} and bind it.
+        /// Creates a new <see cref="IChannel"/> and binds it.
+        /// This overload binds to a <see cref="IPEndPoint"/> for a given <see cref="IPAddress"/> and port.
         /// </summary>
+        /// <param name="inetHost">The <see cref="IPAddress"/> to bind the local "end" to.</param>
+        /// <param name="inetPort">The port to bind the local "end" to.</param>
+        /// <returns>The bound <see cref="IChannel"/>.</returns>
         public Task<IChannel> BindAsync(IPAddress inetHost, int inetPort) => this.BindAsync(new IPEndPoint(inetHost, inetPort));
 
         /// <summary>
-        ///     Create a new {@link Channel} and bind it.
+        /// Creates a new <see cref="IChannel"/> and binds it.
         /// </summary>
+        /// <param name="localAddress">The <see cref="EndPoint"/> instance to bind the local "end" to.</param>
+        /// <returns>The bound <see cref="IChannel"/>.</returns>
         public Task<IChannel> BindAsync(EndPoint localAddress)
         {
             this.Validate();
@@ -307,8 +331,10 @@ static Task DoBind0Async(IChannel channel, EndPoint localAddress)
         protected abstract void Init(IChannel channel);
 
         /// <summary>
-        ///     the {@link ChannelHandler} to use for serving the requests.
+        /// Specifies the <see cref="IChannelHandler"/> to use for serving the requests.
         /// </summary>
+        /// <param name="handler">The <see cref="IChannelHandler"/> to use for serving requests.</param>
+        /// <returns>The <see cref="AbstractBootstrap{TBootstrap,TChannel}"/> instance.</returns>
         public TBootstrap Handler(IChannelHandler handler)
         {
             Contract.Requires(handler != null);
@@ -321,7 +347,7 @@ public TBootstrap Handler(IChannelHandler handler)
         protected IChannelHandler Handler() => this.handler;
 
         /// <summary>
-        ///     Return the configured {@link EventLoopGroup} or {@code null} if non is configured yet.
+        /// Returns the configured <see cref="IEventLoopGroup"/> or <c>null</c> if none is configured yet.
         /// </summary>
         public IEventLoopGroup Group() => this.group;