From 18ec83493c8110cd821b03337a6d09c5f58bc2b6 Mon Sep 17 00:00:00 2001
From: Steven Kirk <grokys@gmail.com>
Date: Sun, 9 Aug 2015 21:08:08 +0200
Subject: [PATCH] Documented PerspexList.

---
 Perspex.Base/Collections/PerspexList.cs | 127 ++++++++++++++++++++++--
 1 file changed, 120 insertions(+), 7 deletions(-)

diff --git a/Perspex.Base/Collections/PerspexList.cs b/Perspex.Base/Collections/PerspexList.cs
index 1c24a52db7..c7a2299aa9 100644
--- a/Perspex.Base/Collections/PerspexList.cs
+++ b/Perspex.Base/Collections/PerspexList.cs
@@ -27,60 +27,91 @@ namespace Perspex.Collections
     {
         private List<T> inner;
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PerspexList{T}"/> class.
+        /// </summary>
         public PerspexList()
             : this(Enumerable.Empty<T>())
         {
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PerspexList{T}"/> class.
+        /// </summary>
+        /// <param name="items">The initial items for the collection.</param>
         public PerspexList(IEnumerable<T> items)
         {
             this.inner = new List<T>(items);
         }
 
+        /// <summary>
+        /// Initializes a new instance of the <see cref="PerspexList{T}"/> class.
+        /// </summary>
+        /// <param name="items">The initial items for the collection.</param>
         public PerspexList(params T[] items)
         {
             this.inner = new List<T>(items);
         }
 
+        /// <summary>
+        /// Raised when a change is made to the collection's items.
+        /// </summary>
         public event NotifyCollectionChangedEventHandler CollectionChanged;
 
+        /// <summary>
+        /// Raised when a property on the collection changes.
+        /// </summary>
         public event PropertyChangedEventHandler PropertyChanged;
 
+        /// <summary>
+        /// Gets the number of items in the collection.
+        /// </summary>
         public int Count
         {
             get { return this.inner.Count; }
         }
 
-        public bool IsReadOnly
-        {
-            get { return false; }
-        }
-
+        /// <inheritdoc/>
         bool IList.IsFixedSize
         {
             get { return false; }
-       }
+        }
 
+        /// <inheritdoc/>
         bool IList.IsReadOnly
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         int ICollection.Count
         {
             get { return this.inner.Count; }
         }
 
+        /// <inheritdoc/>
         bool ICollection.IsSynchronized
         {
             get { return false; }
         }
 
+        /// <inheritdoc/>
         object ICollection.SyncRoot
         {
             get { return null; }
         }
 
+        /// <inheritdoc/>
+        bool ICollection<T>.IsReadOnly
+        {
+            get { return false; }
+        }
+
+        /// <summary>
+        /// Gets or sets the item at the specified index.
+        /// </summary>
+        /// <param name="index">The index.</param>
+        /// <returns>The item.</returns>
         public T this[int index]
         {
             get
@@ -104,13 +135,21 @@ namespace Perspex.Collections
             }
         }
 
+        /// <summary>
+        /// Gets or sets the item at the specified index.
+        /// </summary>
+        /// <param name="index">The index.</param>
+        /// <returns>The item.</returns>
         object IList.this[int index]
         {
             get { return this[index]; }
-
             set { this[index] = (T)value; }
         }
 
+        /// <summary>
+        /// Adds an item to the collection.
+        /// </summary>
+        /// <param name="item">The item.</param>
         public void Add(T item)
         {
             int index = this.inner.Count;
@@ -118,6 +157,10 @@ namespace Perspex.Collections
             this.NotifyAdd(new[] { item }, index);
         }
 
+        /// <summary>
+        /// Adds multiple items to the collection.
+        /// </summary>
+        /// <param name="items">The items.</param>
         public void AddRange(IEnumerable<T> items)
         {
             Contract.Requires<ArgumentNullException>(items != null);
@@ -127,6 +170,9 @@ namespace Perspex.Collections
             this.NotifyAdd((items as IList) ?? items.ToList(), index);
         }
 
+        /// <summary>
+        /// Removes all items from the collection.
+        /// </summary>
         public void Clear()
         {
             var old = this.inner;
@@ -134,32 +180,63 @@ namespace Perspex.Collections
             this.NotifyRemove(old, 0);
         }
 
+        /// <summary>
+        /// Tests if the collection contains the specified item.
+        /// </summary>
+        /// <param name="item">The item.</param>
+        /// <returns>True if the collection contains the item; otherwise false.</returns>
         public bool Contains(T item)
         {
             return this.inner.Contains(item);
         }
 
+        /// <summary>
+        /// Copies the collection's contents to an array.
+        /// </summary>
+        /// <param name="array">The array.</param>
+        /// <param name="arrayIndex">The first index of the array to copy to.</param>
         public void CopyTo(T[] array, int arrayIndex)
         {
             this.inner.CopyTo(array, arrayIndex);
         }
 
+        /// <summary>
+        /// Returns an enumerator that enumerates the items in the collection.
+        /// </summary>
+        /// <returns>An <see cref="IEnumerator{T}"/>.</returns>
         public IEnumerator<T> GetEnumerator()
         {
             return this.inner.GetEnumerator();
         }
 
+        /// <summary>
+        /// Gets the index of the specified item in the collection.
+        /// </summary>
+        /// <param name="item">The item.</param>
+        /// <returns>
+        /// The index of the item or -1 if the item is not contained in the collection.
+        /// </returns>
         public int IndexOf(T item)
         {
             return this.inner.IndexOf(item);
         }
 
+        /// <summary>
+        /// Inserts an item at the specified index.
+        /// </summary>
+        /// <param name="index">The index.</param>
+        /// <param name="item">The item.</param>
         public void Insert(int index, T item)
         {
             this.inner.Insert(index, item);
             this.NotifyAdd(new[] { item }, index);
         }
 
+        /// <summary>
+        /// Inserts multiple items at the specified index.
+        /// </summary>
+        /// <param name="index">The index.</param>
+        /// <param name="items">The items.</param>
         public void InsertRange(int index, IEnumerable<T> items)
         {
             Contract.Requires<ArgumentNullException>(items != null);
@@ -168,6 +245,11 @@ namespace Perspex.Collections
             this.NotifyAdd((items as IList) ?? items.ToList(), index);
         }
 
+        /// <summary>
+        /// Removes an item from the collection.
+        /// </summary>
+        /// <param name="item">The item.</param>
+        /// <returns>True if the item was found and removed, otherwise false.</returns>
         public bool Remove(T item)
         {
             int index = this.inner.IndexOf(item);
@@ -182,6 +264,10 @@ namespace Perspex.Collections
             return false;
         }
 
+        /// <summary>
+        /// Removes multiple items from the collection.
+        /// </summary>
+        /// <param name="items">The items.</param>
         public void RemoveAll(IEnumerable<T> items)
         {
             Contract.Requires<ArgumentNullException>(items != null);
@@ -195,6 +281,10 @@ namespace Perspex.Collections
             }
         }
 
+        /// <summary>
+        /// Removes the item at the specified index.
+        /// </summary>
+        /// <param name="index">The index.</param>
         public void RemoveAt(int index)
         {
             T item = this.inner[index];
@@ -202,6 +292,7 @@ namespace Perspex.Collections
             this.NotifyRemove(new[] { item }, index);
         }
 
+        /// <inheritdoc/>
         int IList.Add(object value)
         {
             int index = this.Count;
@@ -209,46 +300,59 @@ namespace Perspex.Collections
             return index;
         }
 
+        /// <inheritdoc/>
         bool IList.Contains(object value)
         {
             return this.Contains((T)value);
         }
 
+        /// <inheritdoc/>
         void IList.Clear()
         {
             this.Clear();
         }
 
+        /// <inheritdoc/>
         int IList.IndexOf(object value)
         {
             return this.IndexOf((T)value);
         }
 
+        /// <inheritdoc/>
         void IList.Insert(int index, object value)
         {
             this.Insert(index, (T)value);
         }
 
+        /// <inheritdoc/>
         void IList.Remove(object value)
         {
             this.Remove((T)value);
         }
 
+        /// <inheritdoc/>
         void IList.RemoveAt(int index)
         {
             this.RemoveAt(index);
         }
 
+        /// <inheritdoc/>
         void ICollection.CopyTo(Array array, int index)
         {
             this.inner.CopyTo((T[])array, index);
         }
 
+        /// <inheritdoc/>
         IEnumerator IEnumerable.GetEnumerator()
         {
             return this.inner.GetEnumerator();
         }
 
+        /// <summary>
+        /// Raises the <see cref="CollectionChanged"/> event with an add action.
+        /// </summary>
+        /// <param name="t">The items that were added.</param>
+        /// <param name="index">The starting index.</param>
         private void NotifyAdd(IList t, int index)
         {
             if (this.CollectionChanged != null)
@@ -260,6 +364,10 @@ namespace Perspex.Collections
             this.NotifyCountChanged();
         }
 
+        /// <summary>
+        /// Raises the <see cref="PropertyChanged"/> event when the <see cref="Count"/> property
+        /// changes.
+        /// </summary>
         private void NotifyCountChanged()
         {
             if (this.PropertyChanged != null)
@@ -268,6 +376,11 @@ namespace Perspex.Collections
             }
         }
 
+        /// <summary>
+        /// Raises the <see cref="CollectionChanged"/> event with a remove action.
+        /// </summary>
+        /// <param name="t">The items that were removed.</param>
+        /// <param name="index">The starting index.</param>
         private void NotifyRemove(IList t, int index)
         {
             if (this.CollectionChanged != null)