Convert javadoc to C# xmldoc in the DotNetty.Common project (#395)

This is a progressive commit towards completing #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.Common/Concurrency/SingleThreadEventExecutor.cs

@@ -147,10 +147,11 @@ protected void WakeUp(bool inEventLoop)
                 this.Execute(WAKEUP_TASK);
             }
         }
-
-        /**
-          * Add a {@link Runnable} which will be executed on shutdown of this instance
-          */
+
+        /// <summary>
+        /// Adds an <see cref="Action"/> which will be executed on shutdown of this instance.
+        /// </summary>
+        /// <param name="action">The <see cref="Action"/> to run on shutdown.</param>
         public void AddShutdownHook(Action action) 
         {
             if (this.InEventLoop) 
@@ -163,9 +164,11 @@ public void AddShutdownHook(Action action)
             }
         }
 
-        /**
-         * Remove a previous added {@link Runnable} as a shutdown hook
-         */
+        /// <summary>
+        /// Removes a previously added <see cref="Action"/> from the collection of <see cref="Action"/>s which will be
+        /// executed on shutdown of this instance.
+        /// </summary>
+        /// <param name="action">The <see cref="Action"/> to remove.</param>
         public void RemoveShutdownHook(Action action) 
         {
             if (this.InEventLoop) 

src/DotNetty.Common/FastThreadLocal.cs

@@ -11,7 +11,7 @@ public abstract class FastThreadLocal
         static readonly int VariablesToRemoveIndex = InternalThreadLocalMap.NextVariableIndex();
 
         /// <summary>
-        ///     Removes all {@link FastThreadLocal} variables bound to the current thread.  This operation is useful when you
+        ///     Removes all <see cref="FastThreadLocal"/> variables bound to the current thread.  This operation is useful when you
         ///     are in a container environment, and you don't want to leave the thread local variables in the threads you do not
         ///     manage.
         /// </summary>
@@ -41,10 +41,12 @@ public static void RemoveAll()
             }
         }
 
-        /// Destroys the data structure that keeps all {@link FastThreadLocal} variables accessed from
-        /// non-{@link FastThreadLocalThread}s.  This operation is useful when you are in a container environment, and you
-        /// do not want to leave the thread local variables in the threads you do not manage.  Call this method when your
-        /// application is being unloaded from the container.
+        /// <summary>
+        /// Destroys the data structure that keeps all <see cref="FastThreadLocal"/> variables accessed from
+        /// non-<see cref="FastThreadLocal"/>s.  This operation is useful when you are in a container environment, and
+        /// you do not want to leave the thread local variables in the threads you do not manage.  Call this method when
+        /// your application is being unloaded from the container.
+        /// </summary>
         public static void Destroy() => InternalThreadLocalMap.Destroy();
 
         protected static void AddToVariablesToRemove(InternalThreadLocalMap threadLocalMap, FastThreadLocal variable)
@@ -135,7 +137,7 @@ T Initialize(InternalThreadLocalMap threadLocalMap)
         }
 
         /// <summary>
-        ///     Set the value for the specified thread local map. The specified thread local map must be for the current thread.
+        /// Set the value for the specified thread local map. The specified thread local map must be for the current thread.
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public void Set(InternalThreadLocalMap threadLocalMap, T value)
@@ -147,27 +149,32 @@ public void Set(InternalThreadLocalMap threadLocalMap, T value)
         }
 
         /// <summary>
-        ///     Returns {@code true} if and only if this thread-local variable is set.
+        /// Returns <c>true</c> if and only if this thread-local variable is set.
         /// </summary>
         public bool IsSet() => this.IsSet(InternalThreadLocalMap.GetIfSet());
 
         /// <summary>
-        ///     Returns {@code true} if and only if this thread-local variable is set.
-        ///     The specified thread local map must be for the current thread.
+        /// Returns <c>true</c> if and only if this thread-local variable is set.
+        /// The specified thread local map must be for the current thread.
         /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public bool IsSet(InternalThreadLocalMap threadLocalMap) => threadLocalMap != null && threadLocalMap.IsIndexedVariableSet(this.index);
 
         /// <summary>
-        ///     Returns the initial value for this thread-local variable.
+        /// Returns the initial value for this thread-local variable.
         /// </summary>
         protected virtual T GetInitialValue() => null;
 
         public void Remove() => this.Remove(InternalThreadLocalMap.GetIfSet());
 
+        /// <summary>
         /// Sets the value to uninitialized for the specified thread local map;
-        /// a proceeding call to get() will trigger a call to GetInitialValue().
+        /// a proceeding call to <see cref="Get"/> will trigger a call to <see cref="GetInitialValue"/>.
         /// The specified thread local map must be for the current thread.
+        /// </summary>
+        /// <param name="threadLocalMap">
+        /// The <see cref="InternalThreadLocalMap"/> from which this <see cref="FastThreadLocal"/> should be removed.
+        /// </param>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public sealed override void Remove(InternalThreadLocalMap threadLocalMap)
         {
@@ -186,7 +193,7 @@ public sealed override void Remove(InternalThreadLocalMap threadLocalMap)
         }
 
         /// <summary>
-        ///     Invoked when this thread local variable is removed by {@link #remove()}.
+        /// Invoked when this thread local variable is removed by <see cref="Remove()"/>.
         /// </summary>
         protected virtual void OnRemoval(T value)
         {

src/DotNetty.Common/Internal/AppendableCharSequence.cs

@@ -176,8 +176,10 @@ public IAppendable Append(ICharSequence sequence, int start, int end)
             return this;
         }
 
-        // Reset the {@link AppendableCharSequence}. Be aware this will only reset the current internal position and not
-        // shrink the internal char array.
+        /// <summary>
+        /// Resets the <see cref="AppendableCharSequence"/>. Be aware this will only reset the current internal
+        /// position and not shrink the internal char array.
+        /// </summary>
         public void Reset() => this.pos = 0;
 
         public string ToString(int start)
@@ -190,8 +192,10 @@ public string ToString(int start)
 
         public AsciiString ToAsciiString() => this.pos == 0 ? AsciiString.Empty : new AsciiString(this.chars, 0, this.pos, true);
 
-        // Create a new ascii string, this method assumes all chars has been sanitized
-        // to ascii chars when appending to the array
+        /// <summary>
+        /// Create a new ascii string, this method assumes all chars has been sanitized to ascii chars when appending
+        /// to the array.
+        /// </summary>
         [MethodImpl(MethodImplOptions.AggressiveInlining)]
         public unsafe AsciiString SubStringUnsafe(int start, int end)
         {

src/DotNetty.Common/Internal/ConcurrentCircularArrayQueue.cs

@@ -34,28 +34,39 @@ protected ConcurrentCircularArrayQueue(int capacity)
             this.Buffer = new T[actualCapacity + RefArrayAccessUtil.RefBufferPad * 2];
         }
 
-        /// @param index desirable element index
-        /// @return the offset in bytes within the array for a given index.
+        /// <summary>
+        /// Calculates an element offset based on a given array index.
+        /// </summary>
+        /// <param name="index">The desirable element index.</param>
+        /// <returns>The offset in bytes within the array for a given index.</returns>
         protected long CalcElementOffset(long index) => RefArrayAccessUtil.CalcElementOffset(index, this.Mask);
 
-        /// A plain store (no ordering/fences) of an element to a given offset
-        /// @param offset computed via {@link ConcurrentCircularArrayQueue#calcElementOffset(long)}
-        /// @param e a kitty
+        /// <summary>
+        /// A plain store (no ordering/fences) of an element to a given offset.
+        /// </summary>
+        /// <param name="offset">Computed via <see cref="CalcElementOffset"/>.</param>
+        /// <param name="e">A kitty.</param>
         protected void SpElement(long offset, T e) => RefArrayAccessUtil.SpElement(this.Buffer, offset, e);
 
-        /// An ordered store(store + StoreStore barrier) of an element to a given offset
-        /// @param offset computed via {@link ConcurrentCircularArrayQueue#calcElementOffset(long)}
-        /// @param e an orderly kitty
+        /// <summary>
+        /// An ordered store(store + StoreStore barrier) of an element to a given offset.
+        /// </summary>
+        /// <param name="offset">Computed via <see cref="CalcElementOffset"/>.</param>
+        /// <param name="e">An orderly kitty.</param>
         protected void SoElement(long offset, T e) => RefArrayAccessUtil.SoElement(this.Buffer, offset, e);
 
+        /// <summary>
         /// A plain load (no ordering/fences) of an element from a given offset.
-        /// @param offset computed via {@link ConcurrentCircularArrayQueue#calcElementOffset(long)}
-        /// @return the element at the offset
+        /// </summary>
+        /// <param name="offset">Computed via <see cref="CalcElementOffset"/>.</param>
+        /// <returns>The element at the offset.</returns>
         protected T LpElement(long offset) => RefArrayAccessUtil.LpElement(this.Buffer, offset);
 
+        /// <summary>
         /// A volatile load (load + LoadLoad barrier) of an element from a given offset.
-        /// @param offset computed via {@link ConcurrentCircularArrayQueue#calcElementOffset(long)}
-        /// @return the element at the offset
+        /// </summary>
+        /// <param name="offset">Computed via <see cref="CalcElementOffset"/>.</param>
+        /// <returns>The element at the offset.</returns>
         protected T LvElement(long offset) => RefArrayAccessUtil.LvElement(this.Buffer, offset);
 
         public override void Clear()

src/DotNetty.Common/Internal/Logging/AbstractInternalLogger.cs

@@ -7,18 +7,18 @@ namespace DotNetty.Common.Internal.Logging
     using System.Diagnostics.Contracts;
 
     /// <summary>
-    ///     A skeletal implementation of {@link IInternalLogger}.  This class implements
-    ///     all methods that have a { @link InternalLogLevel } parameter by default to call
-    ///     specific logger methods such as {@link #Info(String)} or {@link #isInfoEnabled()}.
+    /// A skeletal implementation of <see cref="IInternalLogger"/>. This class implements
+    /// all methods that have a <see cref="InternalLogLevel"/> parameter by default to call
+    /// specific logger methods such as <see cref="Info(string)"/> or <see cref="InfoEnabled"/>.
     /// </summary>
     public abstract class AbstractInternalLogger : IInternalLogger
     {
         static readonly string EXCEPTION_MESSAGE = "Unexpected exception:";
 
         /// <summary>
-        ///     Creates a new instance.
+        /// Creates a new instance.
         /// </summary>
-        /// <param name="name"></param>
+        /// <param name="name">A friendly name for the new logger instance.</param>
         protected AbstractInternalLogger(string name)
         {
             Contract.Requires(name != null);

src/DotNetty.Common/Internal/Logging/FormattingTuple.cs

@@ -7,7 +7,7 @@ namespace DotNetty.Common.Internal.Logging
     using System.Diagnostics.Contracts;
 
     /// <summary>
-    ///     Holds the results of formatting done by {@link MessageFormatter}.
+    /// Holds the results of formatting done by <see cref="MessageFormatter"/>.
     /// </summary>
     public struct FormattingTuple
     {