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>
-    where ParentType : class {
+  public class Parentable<ParentType> 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
-      heap = new ItemType[capacity];
+      this.capacity = 15; // 15 is equal to 4 complete levels
+      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];
-      --count;
-      trickleDown(0, heap[count]);
+      ItemType result = this.heap[0];
+      --this.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;
-      bubbleUp(count - 1, item);
-      ++version;
+      ++this.count;
+      bubbleUp(this.count - 1, item);
+      ++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)) {
-        heap[index] = heap[parent];
+      while((index > 0) && (this.comparer.Compare(this.heap[parent], item) < 0)) {
+        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];
-      Array.Copy(heap, 0, newHeap, 0, count);
-      heap = newHeap;
+      ItemType[] newHeap = new ItemType[this.capacity];
+      Array.Copy(this.heap, 0, newHeap, 0, this.count);
+      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
-        // during the lifetime of the application -- if at all...
+        // the entire buffer, but since this operation will probably be only called
+        // 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");
     }