Update documentation for OrderBy and ThenBy

Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.OrderBy.md

@@ -0,0 +1,27 @@
+---
+uid: SuperLinq.SuperEnumerable.OrderBy``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},SuperLinq.OrderByDirection)
+example: [*content]
+---
+The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
+[!code-csharp[](SuperLinq/OrderBy/OrderBy1.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.ThenBy``2(System.Linq.IOrderedEnumerable{``0},System.Func{``0,``1},SuperLinq.OrderByDirection)
+example: [*content]
+---
+The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
+[!code-csharp[](SuperLinq/OrderBy/OrderBy1.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.OrderBy``2(System.Collections.Generic.IEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IComparer{``1},SuperLinq.OrderByDirection)
+example: [*content]
+---
+The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
+[!code-csharp[](SuperLinq/OrderBy/OrderBy2.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.ThenBy``2(System.Linq.IOrderedEnumerable{``0},System.Func{``0,``1},System.Collections.Generic.IComparer{``1},SuperLinq.OrderByDirection)
+example: [*content]
+---
+The following code example demonstrates how to sort a sequence using `OrderBy` and `ThenBy`.
+[!code-csharp[](SuperLinq/OrderBy/OrderBy2.linq#L6-)]

Docs/SuperLinq.Docs/apidoc/SuperLinq/OrderBy/OrderBy1.linq

@@ -0,0 +1,24 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var fruits = new[]
+{
+	"grape", "passionfruit", "banana", "Mango",
+	"Orange", "raspberry", "apple", "blueberry",
+};
+
+// Sort the strings first by their length and then
+// alphabetically by passing the identity selector function.
+var result = fruits
+	.OrderBy(fruit => fruit.Length)
+	.ThenBy(fruit => fruit);
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [apple, grape, Mango, banana, Orange, blueberry, raspberry, passionfruit]

Docs/SuperLinq.Docs/apidoc/SuperLinq/OrderBy/OrderBy2.linq

@@ -0,0 +1,24 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var fruits = new[]
+{
+	"grape", "passionfruit", "banana", "Mango",
+	"Orange", "raspberry", "apple", "blueberry",
+};
+
+// Sort the strings first by their length and then
+// alphabetically by passing the identity selector function.
+var result = fruits
+	.OrderBy(fruit => fruit.Length)
+	.ThenBy(fruit => fruit, StringComparer.Ordinal);
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [Mango, apple, grape, Orange, banana, blueberry, raspberry, passionfruit]

Source/SuperLinq/OrderBy.cs

@@ -3,72 +3,156 @@
 public static partial class SuperEnumerable
 {
 	/// <summary>
-	/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
+	///	    Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
-	/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
-	/// <param name="source">The sequence to order</param>
-	/// <param name="keySelector">A key selector function</param>
-	/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
-	/// <returns>An ordered copy of the source sequence</returns>
-
+	/// <typeparam name="T">
+	///	    The type of the elements in the source sequence
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    The type of the key used to order elements
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to order
+	/// </param>
+	/// <param name="keySelector">
+	///	    A key selector function
+	/// </param>
+	/// <param name="direction">
+	///	    A direction in which to order the elements (ascending, descending)
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <returns>
+	///	    An ordered copy of the source sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
+	///     in it's entirety immediately when first element of the returned sequence is consumed. 
+	/// </para>
+	/// </remarks>
 	public static IOrderedEnumerable<T> OrderBy<T, TKey>(this IEnumerable<T> source, Func<T, TKey> keySelector, OrderByDirection direction)
 	{
 		return OrderBy(source, keySelector, null, direction);
 	}
 
 	/// <summary>
-	/// Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
+	///	    Sorts the elements of a sequence in a particular direction (ascending, descending) according to a key
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
-	/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
-	/// <param name="source">The sequence to order</param>
-	/// <param name="keySelector">A key selector function</param>
-	/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
-	/// <param name="comparer">A comparer used to define the semantics of element comparison</param>
-	/// <returns>An ordered copy of the source sequence</returns>
-
+	/// <typeparam name="T">
+	///	    The type of the elements in the source sequence
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    The type of the key used to order elements
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to order
+	/// </param>
+	/// <param name="keySelector">
+	///	    A key selector function
+	/// </param>
+	/// <param name="comparer">
+	///		An <see cref="IComparer{T}"/> to compare keys
+	/// </param>
+	/// <param name="direction">
+	///	    A direction in which to order the elements (ascending, descending)
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <returns>
+	///	    An ordered copy of the source sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
+	///     in it's entirety immediately when first element of the returned sequence is consumed. 
+	/// </para>
+	/// </remarks>
 	public static IOrderedEnumerable<T> OrderBy<T, TKey>(this IEnumerable<T> source, Func<T, TKey> keySelector, IComparer<TKey>? comparer, OrderByDirection direction)
 	{
 		Guard.IsNotNull(source);
 		Guard.IsNotNull(keySelector);
 		return direction == OrderByDirection.Ascending
-				   ? source.OrderBy(keySelector, comparer)
-				   : source.OrderByDescending(keySelector, comparer);
+			? source.OrderBy(keySelector, comparer)
+			: source.OrderByDescending(keySelector, comparer);
 	}
 
 	/// <summary>
-	/// Performs a subsequent ordering of elements in a sequence in a particular direction (ascending, descending) according to a key
+	///	    Performs a subsequent ordering of elements of a sequence in a particular direction (ascending, descending) according to a key
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
-	/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
-	/// <param name="source">The sequence to order</param>
-	/// <param name="keySelector">A key selector function</param>
-	/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
-	/// <returns>An ordered copy of the source sequence</returns>
-
+	/// <typeparam name="T">
+	///	    The type of the elements in the source sequence
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    The type of the key used to order elements
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to order
+	/// </param>
+	/// <param name="keySelector">
+	///	    A key selector function
+	/// </param>
+	/// <param name="direction">
+	///	    A direction in which to order the elements (ascending, descending)
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <returns>
+	///	    An ordered copy of the source sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
+	///     in it's entirety immediately when first element of the returned sequence is consumed. 
+	/// </para>
+	/// </remarks>
 	public static IOrderedEnumerable<T> ThenBy<T, TKey>(this IOrderedEnumerable<T> source, Func<T, TKey> keySelector, OrderByDirection direction)
 	{
 		return ThenBy(source, keySelector, null, direction);
 	}
 
 	/// <summary>
-	/// Performs a subsequent ordering of elements in a sequence in a particular direction (ascending, descending) according to a key
+	///	    Performs a subsequent ordering of elements of a sequence in a particular direction (ascending, descending) according to a key
 	/// </summary>
-	/// <typeparam name="T">The type of the elements in the source sequence</typeparam>
-	/// <typeparam name="TKey">The type of the key used to order elements</typeparam>
-	/// <param name="source">The sequence to order</param>
-	/// <param name="keySelector">A key selector function</param>
-	/// <param name="direction">A direction in which to order the elements (ascending, descending)</param>
-	/// <param name="comparer">A comparer used to define the semantics of element comparison</param>
-	/// <returns>An ordered copy of the source sequence</returns>
-
+	/// <typeparam name="T">
+	///	    The type of the elements in the source sequence
+	/// </typeparam>
+	/// <typeparam name="TKey">
+	///	    The type of the key used to order elements
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence to order
+	/// </param>
+	/// <param name="keySelector">
+	///	    A key selector function
+	/// </param>
+	/// <param name="comparer">
+	///		An <see cref="IComparer{T}"/> to compare keys
+	/// </param>
+	/// <param name="direction">
+	///	    A direction in which to order the elements (ascending, descending)
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="keySelector"/> is <see langword="null"/>.
+	/// </exception>
+	/// <returns>
+	///	    An ordered copy of the source sequence
+	/// </returns>
+	/// <remarks>
+	/// <para>
+	///	    This method is implemented by using deferred execution. However, <paramref name="source"/> will be consumed
+	///     in it's entirety immediately when first element of the returned sequence is consumed. 
+	/// </para>
+	/// </remarks>
 	public static IOrderedEnumerable<T> ThenBy<T, TKey>(this IOrderedEnumerable<T> source, Func<T, TKey> keySelector, IComparer<TKey>? comparer, OrderByDirection direction)
 	{
 		Guard.IsNotNull(source);
 		Guard.IsNotNull(keySelector);
 		return direction == OrderByDirection.Ascending
-				   ? source.ThenBy(keySelector, comparer)
-				   : source.ThenByDescending(keySelector, comparer);
+			? source.ThenBy(keySelector, comparer)
+			: source.ThenByDescending(keySelector, comparer);
 	}
 }