add missing documentation from #47231. (#54837)

src/libraries/System.Linq/src/System/Linq/Distinct.cs

@@ -20,8 +20,31 @@ public static IEnumerable<TSource> Distinct<TSource>(this IEnumerable<TSource> s
             return new DistinctIterator<TSource>(source, comparer);
         }
 
+        /// <summary>Returns distinct elements from a sequence according to a specified key selector function.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <typeparam name="TKey">The type of key to distinguish elements by.</typeparam>
+        /// <param name="source">The sequence to remove duplicate elements from.</param>
+        /// <param name="keySelector">A function to extract the key for each element.</param>
+        /// <returns>An <see cref="IEnumerable{T}" /> that contains distinct elements from the source sequence.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
+        /// <remarks>
+        /// <para>This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic.</para>
+        /// <para>The <see cref="DistinctBy{TSource, TKey}(IEnumerable{TSource}, Func{TSource, TKey})" /> method returns an unordered sequence that contains no duplicate values. The default equality comparer, <see cref="EqualityComparer{T}.Default" />, is used to compare values.</para>
+        /// </remarks>
         public static IEnumerable<TSource> DistinctBy<TSource, TKey>(this IEnumerable<TSource> source, Func<TSource, TKey> keySelector) => DistinctBy(source, keySelector, null);
 
+        /// <summary>Returns distinct elements from a sequence according to a specified key selector function.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <typeparam name="TKey">The type of key to distinguish elements by.</typeparam>
+        /// <param name="source">The sequence to remove duplicate elements from.</param>
+        /// <param name="keySelector">A function to extract the key for each element.</param>
+        /// <param name="comparer">An <see cref="IEqualityComparer{TKey}" /> to compare keys.</param>
+        /// <returns>An <see cref="IEnumerable{T}" /> that contains distinct elements from the source sequence.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
+        /// <remarks>
+        /// <para>This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic.</para>
+        /// <para>The <see cref="DistinctBy{TSource, TKey}(IEnumerable{TSource}, Func{TSource, TKey}, IEqualityComparer{TKey}?)" /> method returns an unordered sequence that contains no duplicate values. If <paramref name="comparer" /> is <see langword="null" />, the default equality comparer, <see cref="EqualityComparer{T}.Default" />, is used to compare values.</para>
+        /// </remarks>
         public static IEnumerable<TSource> DistinctBy<TSource, TKey>(this IEnumerable<TSource> source, Func<TSource, TKey> keySelector, IEqualityComparer<TKey>? comparer)
         {
             if (source is null)

src/libraries/System.Linq/src/System/Linq/ElementAt.cs

@@ -38,15 +38,16 @@ public static TSource ElementAt<TSource>(this IEnumerable<TSource> source, int i
         }
 
         /// <summary>Returns the element at a specified index in a sequence.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
         /// <param name="source">An <see cref="IEnumerable{T}" /> to return an element from.</param>
         /// <param name="index">The index of the element to retrieve, which is either from the start or the end.</param>
-        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
-        /// <exception cref="ArgumentNullException">
-        ///   <paramref name="source" /> is <see langword="null" />.</exception>
-        /// <exception cref="ArgumentOutOfRangeException">
-        ///   <paramref name="index" /> is outside the bounds of the <paramref name="source" /> sequence.
-        /// </exception>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="index" /> is outside the bounds of the <paramref name="source" /> sequence.</exception>
         /// <returns>The element at the specified position in the <paramref name="source" /> sequence.</returns>
+        /// <remarks>
+        /// <para>If the type of <paramref name="source" /> implements <see cref="IList{T}" />, that implementation is used to obtain the element at the specified index. Otherwise, this method obtains the specified element.</para>
+        /// <para>This method throws an exception if <paramref name="index" /> is out of range. To instead return a default value when the specified index is out of range, use the <see cref="O:Enumerable.ElementAtOrDefault" /> method.</para>
+        /// </remarks>
         public static TSource ElementAt<TSource>(this IEnumerable<TSource> source, Index index)
         {
             if (source == null)
@@ -95,15 +96,15 @@ public static TSource ElementAt<TSource>(this IEnumerable<TSource> source, Index
         }
 
         /// <summary>Returns the element at a specified index in a sequence or a default value if the index is out of range.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
         /// <param name="source">An <see cref="IEnumerable{T}" /> to return an element from.</param>
         /// <param name="index">The index of the element to retrieve, which is either from the start or the end.</param>
-        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
-        /// <exception cref="ArgumentNullException">
-        ///   <paramref name="source" /> is <see langword="null" />.
-        /// </exception>
-        /// <returns>
-        ///   <see langword="default" /> if <paramref name="index" /> is outside the bounds of the <paramref name="source" /> sequence; otherwise, the element at the specified position in the <paramref name="source" /> sequence.
-        /// </returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
+        /// <returns><see langword="default" /> if <paramref name="index" /> is outside the bounds of the <paramref name="source" /> sequence; otherwise, the element at the specified position in the <paramref name="source" /> sequence.</returns>
+        /// <remarks>
+        /// <para>If the type of <paramref name="source" /> implements <see cref="IList{T}" />, that implementation is used to obtain the element at the specified index. Otherwise, this method obtains the specified element.</para>
+        /// <para>The default value for reference and nullable types is <see langword="null" />.</para>
+        /// </remarks>
         public static TSource? ElementAtOrDefault<TSource>(this IEnumerable<TSource> source, Index index)
         {
             if (source == null)

src/libraries/System.Linq/src/System/Linq/First.cs

@@ -33,6 +33,12 @@ public static TSource First<TSource>(this IEnumerable<TSource> source, Func<TSou
         public static TSource? FirstOrDefault<TSource>(this IEnumerable<TSource> source) =>
             source.TryGetFirst(out _);
 
+        /// <summary>Returns the first element of a sequence, or a default value if the sequence contains no elements.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <param name="source">The <see cref="IEnumerable{T}" /> to return the first element of.</param>
+        /// <param name="defaultValue">The default value to return if the sequence is empty.</param>
+        /// <returns><paramref name="defaultValue" /> if <paramref name="source" /> is empty; otherwise, the first element in <paramref name="source" />.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
         public static TSource FirstOrDefault<TSource>(this IEnumerable<TSource> source, TSource defaultValue)
         {
             TSource? first = source.TryGetFirst(out bool found);
@@ -42,6 +48,13 @@ public static TSource FirstOrDefault<TSource>(this IEnumerable<TSource> source,
         public static TSource? FirstOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate) =>
             source.TryGetFirst(predicate, out _);
 
+        /// <summary>Returns the first element of the sequence that satisfies a condition or a default value if no such element is found.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <param name="source">An <see cref="IEnumerable{T}" /> to return an element from.</param>
+        /// <param name="predicate">A function to test each element for a condition.</param>
+        /// <param name="defaultValue">The default value to return if the sequence is empty.</param>
+        /// <returns><paramref name="defaultValue" /> if <paramref name="source" /> is empty or if no element passes the test specified by <paramref name="predicate" />; otherwise, the first element in <paramref name="source" /> that passes the test specified by <paramref name="predicate" />.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> or <paramref name="predicate" /> is <see langword="null" />.</exception>
         public static TSource FirstOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, TSource defaultValue)
         {
             TSource? first = source.TryGetFirst(predicate, out bool found);

src/libraries/System.Linq/src/System/Linq/Intersect.cs

@@ -24,8 +24,37 @@ public static IEnumerable<TSource> Intersect<TSource>(this IEnumerable<TSource>
             return IntersectIterator(first, second, comparer);
         }
 
+        /// <summary>Produces the set intersection of two sequences according to a specified key selector function.</summary>
+        /// <typeparam name="TSource">The type of the elements of the input sequences.</typeparam>
+        /// <typeparam name="TKey">The type of key to identify elements by.</typeparam>
+        /// <param name="first">An <see cref="IEnumerable{T}" /> whose distinct elements that also appear in <paramref name="second" /> will be returned.</param>
+        /// <param name="second">An <see cref="IEnumerable{T}" /> whose distinct elements that also appear in the first sequence will be returned.</param>
+        /// <param name="keySelector">A function to extract the key for each element.</param>
+        /// <returns>A sequence that contains the elements that form the set intersection of two sequences.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="first" /> or <paramref name="second" /> is <see langword="null" />.</exception>
+        /// <remarks>
+        /// <para>This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic.</para>
+        /// <para>The intersection of two sets A and B is defined as the set that contains all the elements of A that also appear in B, but no other elements.</para>
+        /// <para>When the object returned by this method is enumerated, `Intersect` yields distinct elements occurring in both sequences in the order in which they appear in <paramref name="first" />.</para>
+        /// <para>The default equality comparer, <see cref="EqualityComparer{T}.Default" />, is used to compare values.</para>
+        /// </remarks>
         public static IEnumerable<TSource> IntersectBy<TSource, TKey>(this IEnumerable<TSource> first, IEnumerable<TKey> second, Func<TSource, TKey> keySelector) => IntersectBy(first, second, keySelector, null);
 
+        /// <summary>Produces the set intersection of two sequences according to a specified key selector function.</summary>
+        /// <typeparam name="TSource">The type of the elements of the input sequences.</typeparam>
+        /// <typeparam name="TKey">The type of key to identify elements by.</typeparam>
+        /// <param name="first">An <see cref="IEnumerable{T}" /> whose distinct elements that also appear in <paramref name="second" /> will be returned.</param>
+        /// <param name="second">An <see cref="IEnumerable{T}" /> whose distinct elements that also appear in the first sequence will be returned.</param>
+        /// <param name="keySelector">A function to extract the key for each element.</param>
+        /// <param name="comparer">An <see cref="IEqualityComparer{TKey}" /> to compare keys.</param>
+        /// <returns>A sequence that contains the elements that form the set intersection of two sequences.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="first" /> or <paramref name="second" /> is <see langword="null" />.</exception>
+        /// <remarks>
+        /// <para>This method is implemented by using deferred execution. The immediate return value is an object that stores all the information that is required to perform the action. The query represented by this method is not executed until the object is enumerated either by calling its `GetEnumerator` method directly or by using `foreach` in Visual C# or `For Each` in Visual Basic.</para>
+        /// <para>The intersection of two sets A and B is defined as the set that contains all the elements of A that also appear in B, but no other elements.</para>
+        /// <para>When the object returned by this method is enumerated, `Intersect` yields distinct elements occurring in both sequences in the order in which they appear in <paramref name="first" />.</para>
+        /// <para>If <paramref name="comparer" /> is <see langword="null" />, the default equality comparer, <see cref="EqualityComparer{T}.Default" />, is used to compare values.</para>
+        /// </remarks>
         public static IEnumerable<TSource> IntersectBy<TSource, TKey>(this IEnumerable<TSource> first, IEnumerable<TKey> second, Func<TSource, TKey> keySelector, IEqualityComparer<TKey>? comparer)
         {
             if (first is null)

src/libraries/System.Linq/src/System/Linq/Last.cs

@@ -33,7 +33,12 @@ public static TSource Last<TSource>(this IEnumerable<TSource> source, Func<TSour
         public static TSource? LastOrDefault<TSource>(this IEnumerable<TSource> source) =>
             source.TryGetLast(out _);
 
-
+        /// <summary>Returns the last element of a sequence, or a default value if the sequence contains no elements.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <param name="source">An <see cref="IEnumerable{T}" /> to return the last element of.</param>
+        /// <param name="defaultValue">The default value to return if the sequence is empty.</param>
+        /// <returns><paramref name="defaultValue" /> if the source sequence is empty; otherwise, the last element in the <see cref="IEnumerable{T}" />.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> is <see langword="null" />.</exception>
         public static TSource LastOrDefault<TSource>(this IEnumerable<TSource> source, TSource defaultValue)
         {
             TSource? last = source.TryGetLast(out bool found);
@@ -43,6 +48,13 @@ public static TSource LastOrDefault<TSource>(this IEnumerable<TSource> source, T
         public static TSource? LastOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate)
             => source.TryGetLast(predicate, out _);
 
+        /// <summary>Returns the last element of a sequence that satisfies a condition or a default value if no such element is found.</summary>
+        /// <typeparam name="TSource">The type of the elements of <paramref name="source" />.</typeparam>
+        /// <param name="source">An <see cref="IEnumerable{T}" /> to return an element from.</param>
+        /// <param name="predicate">A function to test each element for a condition.</param>
+        /// <param name="defaultValue">The default value to return if the sequence is empty.</param>
+        /// <returns><paramref name="defaultValue" /> if the sequence is empty or if no elements pass the test in the predicate function; otherwise, the last element that passes the test in the predicate function.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source" /> or <paramref name="predicate" /> is <see langword="null" />.</exception>
         public static TSource LastOrDefault<TSource>(this IEnumerable<TSource> source, Func<TSource, bool> predicate, TSource defaultValue)
         {
             var last = source.TryGetLast(predicate, out bool found);