suggestions from PR comments

Author: arekbulski

KaitaiStream.cs

@@ -8,7 +8,7 @@ namespace Kaitai
 {
     /// <summary>
     /// The base Kaitai stream which exposes an API for the Kaitai Struct framework.
-    /// It's based off a <code>BinaryReader</code>, which is a little-endian reader.
+    /// It's based off a <c>BinaryReader</c>, which is a little-endian reader.
     /// </summary>
     public partial class KaitaiStream : BinaryReader
     {
@@ -22,7 +22,7 @@ public KaitaiStream(Stream stream) : base(stream)
         }
 
         /// <summary>
-        /// Create a KaitaiStream backed by a closed file (in read-only binary-mode).
+        /// Create a KaitaiStream by opening a file in read-only binary mode (FileStream).
         /// </summary>
         public KaitaiStream(string filename) : base(File.Open(filename, FileMode.Open, FileAccess.Read, FileShare.Read))
         {
@@ -36,23 +36,26 @@ public KaitaiStream(byte[] data) : base(new MemoryStream(data))
         }
 
         /// <summary>
-        /// Used internally.
+        /// Temporary 64-bit buffer for leftover bits left from an unaligned bit 
+        /// read operation. Following unaligned bit operations would consume bits 
+        /// left in this buffer first, and then, if needed, would continue 
+        /// consuming bytes from the stream.
         /// </summary>
         private ulong Bits = 0;
         /// <summary>
-        /// Used internally.
+        /// Number of bits left in <c>Bits</c> buffer.
         /// </summary>
         private int BitsLeft = 0;
 
         /// <summary>
-        /// Used internally.
-        /// Caches the current plaftorm endianness and allows emited bytecode to be optimised. Thanks to @Arlorean.
+        /// Caches the current platform endianness and allows emitted bytecode to be optimized. Thanks to @Arlorean.
+        /// https://github.com/kaitai-io/kaitai_struct_csharp_runtime/pull/9
         /// </summary>
         static readonly bool IsLittleEndian = BitConverter.IsLittleEndian;
 
         static KaitaiStream()
         {
-            compute_single_rotations();
+            computeSingleRotations();
         }
 
         #endregion
@@ -61,7 +64,7 @@ static KaitaiStream()
 
         /// <summary>
         /// Check if the stream position is at the end of the stream (at EOF).
-        /// WARNING: This requires a seekable and tellable stream.
+        /// WARNING: This requires a stream that supports seeking (memory-based or file-based).
         /// </summary>
         public bool IsEof
         {
@@ -70,7 +73,7 @@ public bool IsEof
 
         /// <summary>
         /// Move the stream to a specified absolute position.
-        /// WARNING: This requires a seekable stream.
+        /// WARNING: This requires a stream that supports seeking (memory-based or file-based).
         /// </summary>
         /// <param name="position">The position to seek to, as non-negative integer</param>
         public void Seek(long position)
@@ -80,7 +83,7 @@ public void Seek(long position)
 
         /// <summary>
         /// Get the current position within the stream.
-        /// WARNING: This requires a tellable stream.
+        /// WARNING: This requires a stream that supports seeking (memory-based or file-based).
         /// </summary>
         public long Pos
         {
@@ -89,7 +92,7 @@ public long Pos
 
         /// <summary>
         /// Get the total length of the stream (ie. file size).
-        /// WARNING: This requires a seekable and tellable stream.
+        /// WARNING: This requires a stream that supports seeking (memory-based or file-based).
         /// </summary>
         public long Size
         {
@@ -285,7 +288,11 @@ public double ReadF8le()
         #region Unaligned bit values
 
         /// <summary>
-        /// ???
+        /// Clears the temporary buffer which holds not-yet-consumed parts of 
+        /// the byte, which might have left over after last unaligned bit read 
+        /// operation. Effectively, aligns the pointer in the stream to next 
+        /// whole byte, discarding the rest of partially byte, if it existed. 
+        /// Does nothing if unaligned bit reading is not used.
         /// </summary>
         public void AlignToByte()
         {
@@ -294,8 +301,15 @@ public void AlignToByte()
         }
 
         /// <summary>
-        /// ???
+        /// Read next n bits from the stream. By convention, starts from most 
+        /// significant bits first and goes to least significant bits.
         /// </summary>
+        /// <remarks>
+        /// If n is not a multiple of 8, then bits left over from partially 
+        /// consumed byte would be stored in stream internal buffer. Subsequent 
+        /// calls to this method would consume bits from that buffer first, and 
+        /// then proceed with fetching the new bytes from the stream.
+        /// </remarks>
         public ulong ReadBitsInt(int n)
         {
             int bitsNeeded = n - BitsLeft;
@@ -329,7 +343,7 @@ public ulong ReadBitsInt(int n)
         }
 
         /// <summary>
-        /// Used internally.
+        /// ???
         /// </summary>
         private static ulong GetMaskOnes(int n)
         {
@@ -518,7 +532,7 @@ public byte[] ProcessXor(byte[] data, byte[] key)
         {
             if (key.Length == 1)
                 return ProcessXor(data, key[0]);
-            if (key.Length <= 64 && ByteArrayZero(key))
+            if (key.Length <= 64 && IsByteArrayZero(key))
                 return data;
 
             int dl = data.Length;
@@ -535,14 +549,14 @@ public byte[] ProcessXor(byte[] data, byte[] key)
         /// <summary>
         /// Used internally.
         /// </summary>
-        private static byte[][] precomputed_single_rotations;
+        private static byte[][] precomputedSingleRotations;
 
         /// <summary>
         /// Used internally.
         /// </summary>
-        private static void compute_single_rotations()
+        private static void computeSingleRotations()
         {
-            precomputed_single_rotations = new byte[8][];
+            precomputedSingleRotations = new byte[8][];
             for (int amount = 1; amount < 8; amount++)
             {
                 byte[] translate = new byte[256];
@@ -551,7 +565,7 @@ private static void compute_single_rotations()
                     // formula taken from: http://stackoverflow.com/a/812039
                     translate[i] = (byte) ((i << amount) | (i >> (8 - amount)));
                 }
-                precomputed_single_rotations[amount] = translate;
+                precomputedSingleRotations[amount] = translate;
             }
         }
 
@@ -566,7 +580,7 @@ private static void compute_single_rotations()
         public byte[] ProcessRotateLeft(byte[] data, int amount, int groupSize)
         {
             if (groupSize < 1)
-                throw new Exception("group size must be at least 1 to be valid");
+                throw new ArgumentException("group size must be at least 1 to be valid", "groupSize");
 
             amount = Mod(amount, groupSize * 8);
             if (amount == 0)
@@ -578,7 +592,7 @@ public byte[] ProcessRotateLeft(byte[] data, int amount, int groupSize)
 
             if (groupSize == 1)
             {
-                byte[] translate = precomputed_single_rotations[amount];
+                byte[] translate = precomputedSingleRotations[amount];
 
                 for (int i = 0; i < dl; i++)
                 {
@@ -751,7 +765,7 @@ public static bool ByteArrayEqual(byte[] a, byte[] b)
         /// <summary>
         /// Check if byte array is all zeroes.
         /// </summary>
-        public static bool ByteArrayZero(byte[] a)
+        public static bool IsByteArrayZero(byte[] a)
         {
             foreach (byte x in a)
                 if (x != 0)