Various conformity issues to coding guidelines fixed; documented all exceptions being thrown

git-svn-id: file:///srv/devel/repo-conversion/nusu@7 d2e56fa2-650e-0410-a79f-9358c0239efd

Source/Collections/Parentable.cs

@@ -5,8 +5,7 @@ namespace Nuclex.Support.Collections {
 
   /// <summary>Base class for objects that can be parented to an owner</summary>
   /// <typeparam name="ParentType">Type of the parent object</typeparam>
-  public class Parentable<ParentType>
+  public class Parentable<ParentType> where ParentType : class {
-    where ParentType : class {
 
     /// <summary>Assigns a new parent to this instance</summary>
     internal void SetParent(ParentType parent) {

Source/Collections/PriorityQueue.cs

@@ -78,21 +78,22 @@ namespace Nuclex.Support.Collections {
     /// <param name="comparer">Comparer to use for ordering the items</param>
     public PriorityQueue(IComparer<ItemType> comparer) {
       this.comparer = comparer;
-      capacity = 15; // 15 is equal to 4 complete levels
+      this.capacity = 15; // 15 is equal to 4 complete levels
-      heap = new ItemType[capacity];
+      this.heap = new ItemType[this.capacity];
     }
 
     /// <summary>Takes the item with the highest priority off from the queue</summary>
     /// <returns>The item with the highest priority in the list</returns>
+    /// <exception cref="InvalidOperationException">When the queue is empty</exception>
     public ItemType Dequeue() {
       if(count == 0)
         throw new InvalidOperationException("No items available to dequeue");
 
-      ItemType result = heap[0];
+      ItemType result = this.heap[0];
-      --count;
+      --this.count;
-      trickleDown(0, heap[count]);
+      trickleDown(0, heap[this.count]);
 
-      ++version;
+      ++this.version;
 
       return result;
     }
@@ -100,18 +101,18 @@ namespace Nuclex.Support.Collections {
     /// <summary>Puts an item into the priority queue</summary>
     /// <param name="item">Item to be queued</param>
     public void Enqueue(ItemType item) {
-      if(count == capacity)
+      if(this.count == capacity)
         growHeap();
 
-      ++count;
+      ++this.count;
-      bubbleUp(count - 1, item);
+      bubbleUp(this.count - 1, item);
-      ++version;
+      ++this.version;
     }
 
     /// <summary>Removes all items from the priority queue</summary>
     public void Clear() {
       this.count = 0;
-      ++version;
+      ++this.version;
     }
 
 
@@ -124,7 +125,7 @@ namespace Nuclex.Support.Collections {
     /// <param name="array">Array to copy the priority queue into</param>
     /// <param name="index">Starting index for the destination array</param>
     public void CopyTo(Array array, int index) {
-      Array.Copy(heap, 0, array, index, count);
+      Array.Copy(heap, 0, array, index, this.count);
     }
 
     /// <summary>
@@ -153,27 +154,30 @@ namespace Nuclex.Support.Collections {
       int parent = getParent(index);
 
       // Note: (index > 0) means there is a parent
-      while((index > 0) && (this.comparer.Compare(heap[parent], item) < 0)) {
+      while((index > 0) && (this.comparer.Compare(this.heap[parent], item) < 0)) {
-        heap[index] = heap[parent];
+        this.heap[index] = this.heap[parent];
         index = parent;
         parent = getParent(index);
       }
 
-      heap[index] = item;
+      this.heap[index] = item;
     }
 
-    /// <summary>Moved the item downwards in the heap tree</summary>
+    /// <summary>Move the item downwards in the heap tree</summary>
     /// <param name="index">Index of the item to be moved</param>
     /// <param name="item">Item to be moved</param>
     private void trickleDown(int index, ItemType item) {
       int child = getLeftChild(index);
 
-      while(child < count) {
+      while(child < this.count) {
 
-        if(((child + 1) < count) && (this.comparer.Compare(heap[child], heap[child + 1]) < 0))
+        if(
+          ((child + 1) < this.count) &&
+          (this.comparer.Compare(heap[child], this.heap[child + 1]) < 0)
+        )
           ++child;
 
-        heap[index] = heap[child];
+        this.heap[index] = this.heap[child];
         index = child;
         child = getLeftChild(index);
       }
@@ -197,11 +201,11 @@ namespace Nuclex.Support.Collections {
 
     /// <summary>Increases the size of the priority collection's heap</summary>
     private void growHeap() {
-      capacity = (capacity * 2) + 1;
+      this.capacity = (capacity * 2) + 1;
 
-      ItemType[] newHeap = new ItemType[capacity];
+      ItemType[] newHeap = new ItemType[this.capacity];
-      Array.Copy(heap, 0, newHeap, 0, count);
+      Array.Copy(this.heap, 0, newHeap, 0, this.count);
-      heap = newHeap;
+      this.heap = newHeap;
     }
 
     /// <summary>Returns an enumerator for the priority queue</summary>

Source/Collections/RingMemoryStream.Test.cs

@@ -111,7 +111,7 @@ namespace Nuclex.Support.Collections {
     }
 
     /// <summary>
-    ///   Tests whether the auto reset feature works (resets the buffer point to the
+    ///   Tests whether the auto reset feature works (resets the buffer pointer to the
     ///   left end of the buffer when it gets empty; mainly a performance feature).
     /// </summary>
     [Test]

Source/Collections/RingMemoryStream.cs

@@ -15,6 +15,9 @@ namespace Nuclex.Support.Collections {
     }
 
     /// <summary>Maximum amount of data that will fit into the ring memory stream</summary>
+    /// <exception cref="ArgumentOutOfRangeException">
+    ///   If the reduced capacity is too small for the ring buffer's current data
+    /// </exception>
     public long Capacity {
       get { return this.ringBuffer.Length; }
       set {
@@ -25,8 +28,9 @@ namespace Nuclex.Support.Collections {
           );
 
         // This could be done in a more efficient manner than just replacing
-        // the stream, but this operation will probably be called only once
+        // the entire buffer, but since this operation will probably be only called
-        // during the lifetime of the application -- if at all...
+        // once during the lifetime of the application, if at all, I don't see
+        // the need to optimize it...
         MemoryStream newBuffer = new MemoryStream((int)value);
 
         newBuffer.SetLength(value);
@@ -62,6 +66,7 @@ namespace Nuclex.Support.Collections {
     }
 
     /// <summary>Current cursor position within the stream</summary>
+    /// <exception cref="NotSupportedException">Always</exception>
     public override long Position {
       get { throw new NotSupportedException("The ring buffer does not support seeking"); }
       set { throw new NotSupportedException("The ring buffer does not support seeking"); }
@@ -129,6 +134,7 @@ namespace Nuclex.Support.Collections {
     /// <param name="buffer">Buffer containing the data to append</param>
     /// <param name="offset">Starting index of the data in the buffer</param>
     /// <param name="count">Number of bytes to write to the stream</param>
+    /// <exception cref="OverflowException">When the ring buffer is full</exception>
     public override void Write(byte[] buffer, int offset, int count) {
 
       // The end index lies behind the start index (usual case), so the
@@ -179,12 +185,14 @@ namespace Nuclex.Support.Collections {
     /// <param name="offset">Position to jump to</param>
     /// <param name="origin">Origin towards which to interpret the offset</param>
     /// <returns>The new offset within the stream</returns>
+    /// <exception cref="NotSupportedException">Always</exception>
     public override long Seek(long offset, SeekOrigin origin) {
       throw new NotSupportedException("The ring buffer does not support seeking");
     }
 
     /// <summary>Changes the length of the stream</summary>
     /// <param name="value">New length to resize the stream to</param>
+    /// <exception cref="NotSupportedException">Always</exception>
     public override void SetLength(long value) {
       throw new NotSupportedException("This operation is not supported");
     }

Source/Licensing/LicenseKey.cs

@@ -25,11 +25,48 @@ namespace Nuclex.Licensing {
     /// <summary>Parses the license key contained in a string</summary>
     /// <param name="key">String containing a license key that is to be parsed</param>
     /// <returns>The license key parsed from provided string</returns>
+    /// <exception cref="ArgumentException">
+    ///   When the provided string is not a license key
+    /// </exception>
     public static LicenseKey Parse(string key) {
-      LicenseKey newKey = new LicenseKey();
+      key = key.Replace(" ", string.Empty).Replace("-", string.Empty).ToUpper();
-      newKey.parse(key);
+      if(key.Length != 25)
+        throw new ArgumentException("This is not a license key");
 
-      return newKey;
+      BitArray bits = new BitArray(128);
+      uint sequence;
+
+      // Convert the first 4 sequences of 6 chars into 124 bits
+      for(int j = 0; j < 4; j++) {
+
+        sequence =
+          (uint)codeTable.IndexOf(key[j * 6 + 5]) * 60466176 +
+          (uint)codeTable.IndexOf(key[j * 6 + 4]) * 1679616 +
+          (uint)codeTable.IndexOf(key[j * 6 + 3]) * 46656 +
+          (uint)codeTable.IndexOf(key[j * 6 + 2]) * 1296 +
+          (uint)codeTable.IndexOf(key[j * 6 + 1]) * 36 +
+          (uint)codeTable.IndexOf(key[j * 6 + 0]);
+
+        for(int i = 0; i < 31; i++)
+          bits[j * 31 + i] = (sequence & powersOfTwo[i, 1]) != 0;
+
+      }
+
+      // Append the remaining character's 4 bits
+      sequence = (uint)codeTable.IndexOf(key[24]);
+      bits[124] = (sequence & powersOfTwo[4, 1]) != 0;
+      bits[125] = (sequence & powersOfTwo[3, 1]) != 0;
+      bits[126] = (sequence & powersOfTwo[2, 1]) != 0;
+      bits[127] = (sequence & powersOfTwo[1, 1]) != 0;
+
+      // Revert the mangling that was applied to the key when encoding...
+      unmangle(bits);
+
+      // ...and we've got our GUID back!
+      byte[] guidBytes = new byte[16];
+      bits.CopyTo(guidBytes, 0);
+
+      return new LicenseKey(new Guid(guidBytes));
     }
 
     /// <summary>Initializes a new, empty license key</summary>
@@ -38,26 +75,29 @@ namespace Nuclex.Licensing {
     /// <summary>Initializes the license key from a GUID</summary>
     /// <param name="source">GUID that is used to create the license key</param>
     public LicenseKey(Guid source) {
-      guid = source;
+      this.guid = source;
     }
 
     /// <summary>Accesses the four integer values within a license key</summary>
+    /// <exception cref="IndexOutOfRangeException">
+    ///   When the index lies outside of the key's fields
+    /// </exception>
     public int this[int index] {
       get {
         if((index < 0) || (index > 3))
           throw new IndexOutOfRangeException("Index out of range");
 
-        return BitConverter.ToInt32(guid.ToByteArray(), index * 4);
+        return BitConverter.ToInt32(this.guid.ToByteArray(), index * 4);
       }
       set {
         if((index < 0) || (index > 3))
           throw new IndexOutOfRangeException("Index out of range");
 
-        using(MemoryStream guidBytes = new MemoryStream(guid.ToByteArray())) {
+        using(MemoryStream guidBytes = new MemoryStream(this.guid.ToByteArray())) {
           guidBytes.Position = index * 4;
           new BinaryWriter(guidBytes).Write(value);
 
-          guid = new Guid(guidBytes.ToArray());
+          this.guid = new Guid(guidBytes.ToArray());
         }
       }
     }
@@ -65,13 +105,13 @@ namespace Nuclex.Licensing {
     /// <summary>Converts the license key into a GUID</summary>
     /// <returns>The GUID created from the license key</returns>
     public Guid ToGuid() {
-      return guid;
+      return this.guid;
     }
 
     /// <summary>Converts the license key into a byte array</summary>
     /// <returns>A byte array containing the converted license key</returns>
     public byte[] ToByteArray() {
-      return guid.ToByteArray();
+      return this.guid.ToByteArray();
     }
 
     /// <summary>Converts the license key to a string</summary>
@@ -80,7 +120,7 @@ namespace Nuclex.Licensing {
       StringBuilder resultBuilder = new StringBuilder();
 
       // Build a bit array from the input data
-      BitArray bits = new BitArray(guid.ToByteArray());
+      BitArray bits = new BitArray(this.guid.ToByteArray());
       mangle(bits);
 
       int sequence = 0;
@@ -152,49 +192,6 @@ namespace Nuclex.Licensing {
       }
     }
 
-    /// <summary>Parses a license key from a string</summary>
-    /// <param name="key">String the license key is read from</param>
-    /// <returns>The license key parsed from the provided string</returns>
-    private void parse(string key) {
-      key = key.Replace(" ", string.Empty).Replace("-", string.Empty).ToUpper();
-      if(key.Length != 25)
-        throw new ArgumentException("This is not a license key");
-
-      BitArray bits = new BitArray(128);
-      uint sequence;
-
-      // Convert the first 4 sequences of 6 chars into 124 bits
-      for(int j = 0; j < 4; j++) {
-
-        sequence =
-          (uint)codeTable.IndexOf(key[j * 6 + 5]) * 60466176 +
-          (uint)codeTable.IndexOf(key[j * 6 + 4]) * 1679616 +
-          (uint)codeTable.IndexOf(key[j * 6 + 3]) * 46656 +
-          (uint)codeTable.IndexOf(key[j * 6 + 2]) * 1296 +
-          (uint)codeTable.IndexOf(key[j * 6 + 1]) * 36 +
-          (uint)codeTable.IndexOf(key[j * 6 + 0]);
-
-        for(int i = 0; i < 31; i++)
-          bits[j * 31 + i] = (sequence & powersOfTwo[i, 1]) != 0;
-
-      }
-
-      // Append the remaining character's 4 bits
-      sequence = (uint)codeTable.IndexOf(key[24]);
-      bits[124] = (sequence & powersOfTwo[4, 1]) != 0;
-      bits[125] = (sequence & powersOfTwo[3, 1]) != 0;
-      bits[126] = (sequence & powersOfTwo[2, 1]) != 0;
-      bits[127] = (sequence & powersOfTwo[1, 1]) != 0;
-
-      // Revert the mangling that was applied to the key when encoding...
-      unmangle(bits);
-
-      // ...and we've got our GUID back!
-      byte[] guidBytes = new byte[16];
-      bits.CopyTo(guidBytes, 0);
-      guid = new Guid(guidBytes);
-    }
-
     /// <summary>Table with the individual characters in a key</summary>
     private static readonly string codeTable =
       "0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ";

Source/Serialization/IBinarySerializable.cs

@@ -18,7 +18,7 @@ namespace Nuclex.Support.Serialization {
     /// <param name="reader">Reader to use for reading the object's state</param>
     void Load(BinaryReader reader);
     
-    /// <summary>Save the object's state into a serialized representation</summary>
+    /// <summary>Saves the object's state into a serialized representation</summary>
     /// <param name="writer">Writer to use for writing the object's state</param>
     void Save(BinaryWriter writer);