From b661798a848de8dc8ae4dd614b7da834a45e61b6 Mon Sep 17 00:00:00 2001
From: Stuart Turner <stuart@turner-isageek.com>
Date: Mon, 4 Sep 2023 10:08:56 -0500
Subject: [PATCH] Update documentation for `ForEach`

---
 .../SuperLinq.SuperEnumerable.ForEach.md      | 13 ++++++
 .../apidoc/SuperLinq/ForEach/ForEach1.linq    | 13 ++++++
 .../apidoc/SuperLinq/ForEach/ForEach2.linq    | 13 ++++++
 Source/SuperLinq/ForEach.cs                   | 46 ++++++++++++-------
 4 files changed, 69 insertions(+), 16 deletions(-)
 create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.ForEach.md
 create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach1.linq
 create mode 100644 Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach2.linq

diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.ForEach.md b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.ForEach.md
new file mode 100644
index 000000000..60029999a
--- /dev/null
+++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq.SuperEnumerable.ForEach.md
@@ -0,0 +1,13 @@
+---
+uid: SuperLinq.SuperEnumerable.ForEach``1(System.Collections.Generic.IEnumerable{``0},System.Action{``0})
+example: [*content]
+---
+The following code example demonstrates how to immediately execute an action on every element of a sequence using `ForEach`.
+[!code-csharp[](SuperLinq/ForEach/ForEach1.linq#L6-)]
+
+---
+uid: SuperLinq.SuperEnumerable.ForEach``1(System.Collections.Generic.IEnumerable{``0},System.Action{``0,System.Int32})
+example: [*content]
+---
+The following code example demonstrates how to immediately execute an action on every element of a sequence using `ForEach`.
+[!code-csharp[](SuperLinq/ForEach/ForEach2.linq#L6-)]
diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach1.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach1.linq
new file mode 100644
index 000000000..935f4c098
--- /dev/null
+++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach1.linq
@@ -0,0 +1,13 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = Enumerable.Range(1, 5);
+
+// Fold a sequence into a single value.
+sequence
+	.ForEach(x => Console.Write($"{x}, "));
+
+// This code produces the following output:
+// 1, 2, 3, 4, 5, 
diff --git a/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach2.linq b/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach2.linq
new file mode 100644
index 000000000..ed5f638b3
--- /dev/null
+++ b/Docs/SuperLinq.Docs/apidoc/SuperLinq/ForEach/ForEach2.linq
@@ -0,0 +1,13 @@
+<Query Kind="Statements">
+  <NuGetReference>SuperLinq</NuGetReference>
+  <Namespace>SuperLinq</Namespace>
+</Query>
+
+var sequence = Enumerable.Range(1, 5);
+
+// Fold a sequence into a single value.
+sequence
+	.ForEach((x, i) => Console.Write($"({x}, {i}), "));
+
+// This code produces the following output:
+// (1, 0), (2, 1), (3, 2), (4, 3), (5, 4), 
diff --git a/Source/SuperLinq/ForEach.cs b/Source/SuperLinq/ForEach.cs
index fe1d7d457..1e1264d98 100644
--- a/Source/SuperLinq/ForEach.cs
+++ b/Source/SuperLinq/ForEach.cs
@@ -3,15 +3,22 @@
 public partial class SuperEnumerable
 {
 	/// <summary>
-	/// Immediately executes the given action on each element in the source sequence.
+	///	    Immediately executes the given action on each element in the source sequence.
 	/// </summary>
-	/// <typeparam name="TSource">The type of the elements in the sequence</typeparam>
-	/// <param name="source">The sequence of elements</param>
-	/// <param name="action">The action to execute on each element</param>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="action"/> is <see
-	/// langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///	    The type of the elements in the sequence
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence of elements
+	/// </param>
+	/// <param name="action">
+	///	    The action to execute on each element
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="action"/> is <see langword="null"/>.
+	/// </exception>
 	/// <remarks>
-	/// This operator executes immediately.
+	///	    This operator executes immediately.
 	/// </remarks>
 	public static void ForEach<TSource>(this IEnumerable<TSource> source, Action<TSource> action)
 	{
@@ -23,17 +30,24 @@ public static void ForEach<TSource>(this IEnumerable<TSource> source, Action<TSo
 	}
 
 	/// <summary>
-	/// Immediately executes the given action on each element in the source sequence. Each element's index is used in
-	/// the logic of the action.
+	///	    Immediately executes the given action on each element in the source sequence. Each element's index is used
+	///     in the logic of the action.
 	/// </summary>
-	/// <typeparam name="TSource">The type of the elements in the sequence</typeparam>
-	/// <param name="source">The sequence of elements</param>
-	/// <param name="action">The action to execute on each element; the second parameter of the action represents the
-	/// index of the source element.</param>
-	/// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="action"/> is <see
-	/// langword="null"/>.</exception>
+	/// <typeparam name="TSource">
+	///	    The type of the elements in the sequence
+	/// </typeparam>
+	/// <param name="source">
+	///	    The sequence of elements
+	/// </param>
+	/// <param name="action">
+	///	    The action to execute on each element; the second parameter of the action represents the index of the source
+	///     element.
+	/// </param>
+	/// <exception cref="ArgumentNullException">
+	///	    <paramref name="source"/> or <paramref name="action"/> is <see langword="null"/>.
+	/// </exception>
 	/// <remarks>
-	/// This operator executes immediately.
+	///	    This operator executes immediately.
 	/// </remarks>
 	public static void ForEach<TSource>(this IEnumerable<TSource> source, Action<TSource, int> action)
 	{