From 7de4bf836e7bb75d9c44d27f016a56f3a31ea89f Mon Sep 17 00:00:00 2001
From: Steven Kirk <grokys@gmail.com>
Date: Tue, 5 May 2015 11:59:32 +0200
Subject: [PATCH] Documented newly added classes.

---
 Perspex.Base/PriorityBindingEntry.cs | 12 +++++
 Perspex.Base/PriorityLevel.cs        | 68 ++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)

diff --git a/Perspex.Base/PriorityBindingEntry.cs b/Perspex.Base/PriorityBindingEntry.cs
index 8b6aca589a..6a62dbed1b 100644
--- a/Perspex.Base/PriorityBindingEntry.cs
+++ b/Perspex.Base/PriorityBindingEntry.cs
@@ -18,11 +18,20 @@ namespace Perspex
         /// </summary>
         private IDisposable subscription;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PriorityBindingEntry"/> class.
+        /// </summary>
+        /// <param name="index">
+        /// The binding index. Later bindings should have higher indexes.
+        /// </param>
         public PriorityBindingEntry(int index)
         {
             this.Index = index;
         }
 
+        /// <summary>
+        /// Gets the observable associated with the entry.
+        /// </summary>
         public IObservable<object> Observable { get; private set; }
 
         /// <summary>
@@ -34,6 +43,9 @@ namespace Perspex
             private set;
         }
 
+        /// <summary>
+        /// Gets the binding entry index. Later bindings will have higher indexes.
+        /// </summary>
         public int Index
         {
             get;
diff --git a/Perspex.Base/PriorityLevel.cs b/Perspex.Base/PriorityLevel.cs
index f8bdf23b99..e9ce948b38 100644
--- a/Perspex.Base/PriorityLevel.cs
+++ b/Perspex.Base/PriorityLevel.cs
@@ -10,14 +10,50 @@ namespace Perspex
     using System.Collections.Generic;
     using System.Reactive.Disposables;
 
+    /// <summary>
+    /// Stores bindings for a priority level in a <see cref="PriorityValue"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>
+    /// Each priority level in a <see cref="PriorityValue"/> has a current <see cref="Value"/>, 
+    /// a list of <see cref="Bindings"/> and a <see cref="DirectValue"/>. When there are no 
+    /// bindings present, or all bindings return <see cref="PerspexProperty.UnsetValue"/> then
+    /// <code>Value</code> will equal <code>DirectValue</code>. 
+    /// </para>
+    /// <para>
+    /// When there are bindings present, then the latest added binding that doesn't return 
+    /// <code>UnsetValue</code> will take precedence. The active binding is returned by the 
+    /// <see cref="ActiveBindingIndex"/> property (which refers to the active binding's 
+    /// <see cref="PriorityBindingEntry.Index"/> property rather than the index in 
+    /// <code>Bindings</code>).
+    /// </para>
+    /// <para>
+    /// If <code>DirectValue</code> is set while a binding is active, then it will replace the
+    /// current value until the active binding fires again/
+    /// </para>
+    /// </remarks>
     internal class PriorityLevel
     {
+        /// <summary>
+        /// Method called when current value changes.
+        /// </summary>
         private Action<PriorityLevel> changed;
 
+        /// <summary>
+        /// The current direct value.
+        /// </summary>
         private object directValue;
 
+        /// <summary>
+        /// The index of the next <see cref="PriorityBindingEntry"/>.
+        /// </summary>
         private int nextIndex;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PriorityLevel"/> class.
+        /// </summary>
+        /// <param name="priority">The priority.</param>
+        /// <param name="changed">A method to be called when the current value changes.</param>
         public PriorityLevel(
             int priority, 
             Action<PriorityLevel> changed)
@@ -31,8 +67,14 @@ namespace Perspex
             this.Bindings = new LinkedList<PriorityBindingEntry>();
         }
 
+        /// <summary>
+        /// Gets the priority of this level.
+        /// </summary>
         public int Priority { get; }
 
+        /// <summary>
+        /// Gets or sets the direct value for this priority level.
+        /// </summary>
         public object DirectValue
         {
             get
@@ -47,12 +89,27 @@ namespace Perspex
             }
         }
 
+        /// <summary>
+        /// Gets the current binding for the priority level.
+        /// </summary>
         public object Value { get; private set; }
 
+        /// <summary>
+        /// Gets the <see cref="PriorityBindingEntry.Index"/> value of the active binding, or -1 
+        /// if no binding is active.
+        /// </summary>
         public int ActiveBindingIndex { get; private set; }
 
+        /// <summary>
+        /// Gets the bindings for the priority level.
+        /// </summary>
         public LinkedList<PriorityBindingEntry> Bindings { get; }
 
+        /// <summary>
+        /// Adds a binding.
+        /// </summary>
+        /// <param name="binding">The binding to add.</param>
+        /// <returns>A disposable used to remove the binding.</returns>
         public IDisposable Add(IObservable<object> binding)
         {
             Contract.Requires<ArgumentNullException>(binding != null);
@@ -73,6 +130,10 @@ namespace Perspex
             });
         }
 
+        /// <summary> 
+        /// Invoked when an entry in <see cref="Bindings"/> changes value.
+        /// </summary>
+        /// <param name="entry">The entry that changed.</param>
         private void Changed(PriorityBindingEntry entry)
         {
             if (entry.Index >= this.ActiveBindingIndex)
@@ -90,6 +151,10 @@ namespace Perspex
             }
         }
 
+        /// <summary> 
+        /// Invoked when an entry in <see cref="Bindings"/> completes.
+        /// </summary>
+        /// <param name="entry">The entry that completed.</param>
         private void Completed(PriorityBindingEntry entry)
         {
             this.Bindings.Remove(entry);
@@ -100,6 +165,9 @@ namespace Perspex
             }
         }
 
+        /// <summary> 
+        /// Activates the first binding that has a value.
+        /// </summary>
         private void ActivateFirstBinding()
         {
             foreach (var binding in this.Bindings)