Update documentation for Defer

Author: viceroypenguin

Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.Defer.md

@@ -0,0 +1,6 @@
+---
+uid: SuperLinq.SuperEnumerable.Defer``1(System.Func{System.Collections.Generic.IEnumerable{``0}})
+example: [*content]
+---
+The following code example demonstrates how to defer the execution of a method that returns an enumerable using `Defer`.
+[!code-csharp[](SuperLinq/Defer/Defer.linq#L6-)]

Docs/SuperLinq.Docs/apidoc/SuperLinq/Defer/Defer.linq

@@ -0,0 +1,28 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var count = 3;
+
+// Use a function to create a sequence at execution time
+var result = SuperEnumerable
+	.Defer(() => Enumerable.Range(1, count));
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+	
+// changing count changes the length of the sequence 
+// returned by the function given to Defer
+count = 5;
+
+Console.WriteLine(
+	"[" +
+	string.Join(", ", result) +
+	"]");
+
+// This code produces the following output:
+// [1, 2, 3]
+// [1, 2, 3, 4, 5]

Source/SuperLinq/Defer.cs

@@ -6,13 +6,36 @@ namespace SuperLinq;
 public static partial class SuperEnumerable
 {
 	/// <summary>
-	/// Creates an enumerable sequence based on an enumerable factory function.
+	///	    Creates an enumerable sequence based on an enumerable factory function.
 	/// </summary>
-	/// <typeparam name="TResult">Result sequence element type.</typeparam>
-	/// <param name="enumerableFactory">Enumerable factory function.</param>
-	/// <returns>Sequence that will invoke the enumerable factory upon iteration.</returns>
-	/// <exception cref="ArgumentNullException"><paramref name="enumerableFactory"/> is <see
-	/// langword="null"/>.</exception>
+	/// <typeparam name="TResult">
+	///	    Result sequence element type.
+	/// </typeparam>
+	/// <param name="enumerableFactory">
+	///	    Enumerable factory function.
+	/// </param>
+	/// <returns>
+	///	    Sequence that will invoke the enumerable factory upon iteration.
+	/// </returns>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="enumerableFactory"/> is <see langword="null"/>.
+	/// </exception>
+	/// <exception cref="ArgumentNullException">
+	///	    (Thrown lazily) The sequence <c>source</c> returned by <paramref name="enumerableFactory"/> is <see
+	///     langword="null"/>.
+	/// </exception>
+	/// <remarks>
+	/// <para>
+	///	    <paramref name="enumerableFactory"/> is not run until the sequence returned by <see
+	///	    cref="Defer{TResult}(Func{IEnumerable{TResult}})"/> is enumerated. At enumeration, <paramref
+	///	    name="enumerableFactory"/> is executed and the sequence returned is enumerated in a streaming manner and
+	///	    values are returned similarly.
+	/// </para>
+	/// <para>
+	///	    <paramref name="enumerableFactory"/> is executed each time the sequence returned by <see
+	///	    cref="Defer{TResult}(Func{IEnumerable{TResult}})"/> is enumerated.
+	/// </para>
+	/// </remarks>
 	public static IEnumerable<TResult> Defer<TResult>(Func<IEnumerable<TResult>> enumerableFactory)
 	{
 		Guard.IsNotNull(enumerableFactory);
@@ -21,7 +44,10 @@ public static IEnumerable<TResult> Defer<TResult>(Func<IEnumerable<TResult>> enu
 
 		static IEnumerable<TResult> Core(Func<IEnumerable<TResult>> enumerableFactory)
 		{
-			foreach (var el in enumerableFactory())
+			var source = enumerableFactory();
+			Guard.IsNotNull(source);
+
+			foreach (var el in source)
 				yield return el;
 		}
 	}