Merge pull request #1099 from akarnokd/IAExMethodDocs_1129

Document AsyncEnumerableEx methods

Ix.NET/Source/System.Interactive.Async/System/Linq/AsyncEnumerableEx.cs

@@ -4,6 +4,10 @@
 
 namespace System.Linq
 {
+    /// <summary>
+    /// Provides an additional set of extension methods for writing in-memory queries, transformations of async-enumerable sequences.
+    /// </summary>
+    /// <seealso cref="AsyncEnumerable"/>
     public static partial class AsyncEnumerableEx
     {
     }

Ix.NET/Source/System.Interactive.Async/System/Linq/Operators/Amb.cs

@@ -10,6 +10,14 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerableEx
     {
+        /// <summary>
+        /// Propagates the async-enumerable sequence that reacts first.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="first">First async-enumerable sequence.</param>
+        /// <param name="second">Second async-enumerable sequence.</param>
+        /// <returns>An async-enumerable sequence that surfaces either of the given sequences, whichever reacted first.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="first"/> or <paramref name="second"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Amb<TSource>(this IAsyncEnumerable<TSource> first, IAsyncEnumerable<TSource> second)
         {
             if (first == null)
@@ -140,6 +148,13 @@ await using (winner.ConfigureAwait(false))
             }
         }
 
+        /// <summary>
+        /// Propagates the async-enumerable sequence that reacts first.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="sources">Observable sources competing to react first.</param>
+        /// <returns>An async-enumerable sequence that surfaces any of the given sequences, whichever reacted first.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Amb<TSource>(params IAsyncEnumerable<TSource>[] sources)
         {
             if (sources == null)
@@ -243,6 +258,13 @@ await using (winner.ConfigureAwait(false))
             }
         }
 
+        /// <summary>
+        /// Propagates the async-enumerable sequence that reacts first.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="sources">Observable sources competing to react first.</param>
+        /// <returns>An async-enumerable sequence that surfaces any of the given sequences, whichever reacted first.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Amb<TSource>(this IEnumerable<IAsyncEnumerable<TSource>> sources)
         {
             if (sources == null)

Ix.NET/Source/System.Interactive.Async/System/Linq/Operators/Buffer.cs

@@ -10,6 +10,15 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerableEx
     {
+        /// <summary>
+        /// Projects each element of an async-enumerable sequence into consecutive non-overlapping buffers which are produced based on element count information.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence, and in the lists in the result sequence.</typeparam>
+        /// <param name="source">Source sequence to produce buffers over.</param>
+        /// <param name="count">Length of each buffer.</param>
+        /// <returns>An async-enumerable sequence of buffers.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is less than or equal to zero.</exception>
         public static IAsyncEnumerable<IList<TSource>> Buffer<TSource>(this IAsyncEnumerable<TSource> source, int count)
         {
             if (source == null)
@@ -42,6 +51,16 @@ await foreach (var item in source.WithCancellation(cancellationToken).ConfigureA
             }
         }
 
+        /// <summary>
+        /// Projects each element of an async-enumerable sequence into zero or more buffers which are produced based on element count information.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence, and in the lists in the result sequence.</typeparam>
+        /// <param name="source">Source sequence to produce buffers over.</param>
+        /// <param name="count">Length of each buffer.</param>
+        /// <param name="skip">Number of elements to skip between creation of consecutive buffers.</param>
+        /// <returns>An async-enumerable sequence of buffers.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
+        /// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> or <paramref name="skip"/> is less than or equal to zero.</exception>
         public static IAsyncEnumerable<IList<TSource>> Buffer<TSource>(this IAsyncEnumerable<TSource> source, int count, int skip)
         {
             if (source == null)

Ix.NET/Source/System.Interactive.Async/System/Linq/Operators/Catch.cs

@@ -16,6 +16,15 @@ public static partial class AsyncEnumerableEx
         //
         //         catch (TException ex) when(!(ex is OperationCanceledException oce && oce.CancellationToken == cancellationToken))
 
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception of the specified type with the async-enumerable sequence produced by the handler.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence and sequences returned by the exception handler function.</typeparam>
+        /// <typeparam name="TException">The type of the exception to catch and handle. Needs to derive from <see cref="Exception"/>.</typeparam>
+        /// <param name="source">Source sequence.</param>
+        /// <param name="handler">Exception handler function, producing another async-enumerable sequence.</param>
+        /// <returns>An async-enumerable sequence containing the source sequence's elements, followed by the elements produced by the handler's resulting async-enumerable sequence in case an exception occurred.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="handler"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource, TException>(this IAsyncEnumerable<TSource> source, Func<TException, IAsyncEnumerable<TSource>> handler)
             where TException : Exception
         {
@@ -70,6 +79,15 @@ await foreach (var item in err.WithCancellation(cancellationToken).ConfigureAwai
             }
         }
 
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception of the specified type with the async-enumerable sequence produced asynchronously by the handler.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence and sequences returned by the exception handler function.</typeparam>
+        /// <typeparam name="TException">The type of the exception to catch and handle. Needs to derive from <see cref="Exception"/>.</typeparam>
+        /// <param name="source">Source sequence.</param>
+        /// <param name="handler">Exception handler function, producing another async-enumerable sequence asynchronously.</param>
+        /// <returns>An async-enumerable sequence containing the source sequence's elements, followed by the elements produced by the handler's resulting async-enumerable sequence in case an exception occurred.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="handler"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource, TException>(this IAsyncEnumerable<TSource> source, Func<TException, ValueTask<IAsyncEnumerable<TSource>>> handler)
             where TException : Exception
         {
@@ -125,6 +143,15 @@ await foreach (var item in err.WithCancellation(cancellationToken).ConfigureAwai
         }
 
 #if !NO_DEEP_CANCELLATION
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception of the specified type with the async-enumerable sequence produced asynchronously (cancellable) by the handler.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence and sequences returned by the exception handler function.</typeparam>
+        /// <typeparam name="TException">The type of the exception to catch and handle. Needs to derive from <see cref="Exception"/>.</typeparam>
+        /// <param name="source">Source sequence.</param>
+        /// <param name="handler">Exception handler function, producing another async-enumerable sequence asynchronously while supporting cancellation.</param>
+        /// <returns>An async-enumerable sequence containing the source sequence's elements, followed by the elements produced by the handler's resulting async-enumerable sequence in case an exception occurred.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="handler"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource, TException>(this IAsyncEnumerable<TSource> source, Func<TException, CancellationToken, ValueTask<IAsyncEnumerable<TSource>>> handler)
             where TException : Exception
         {
@@ -180,6 +207,13 @@ await foreach (var item in err.WithCancellation(cancellationToken).ConfigureAwai
         }
 #endif
 
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception with the next async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source and handler sequences.</typeparam>
+        /// <param name="sources">Observable sequences to catch exceptions for.</param>
+        /// <returns>An async-enumerable sequence containing elements from consecutive source sequences until a source sequence terminates successfully.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource>(this IEnumerable<IAsyncEnumerable<TSource>> sources)
         {
             if (sources == null)
@@ -188,6 +222,13 @@ public static IAsyncEnumerable<TSource> Catch<TSource>(this IEnumerable<IAsyncEn
             return CatchCore(sources);
         }
 
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception with the next async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source and handler sequences.</typeparam>
+        /// <param name="sources">Observable sequences to catch exceptions for.</param>
+        /// <returns>An async-enumerable sequence containing elements from consecutive source sequences until a source sequence terminates successfully.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource>(params IAsyncEnumerable<TSource>[] sources)
         {
             if (sources == null)
@@ -196,6 +237,14 @@ public static IAsyncEnumerable<TSource> Catch<TSource>(params IAsyncEnumerable<T
             return CatchCore(sources);
         }
 
+        /// <summary>
+        /// Continues an async-enumerable sequence that is terminated by an exception with the next async-enumerable sequence.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequence and handler sequence.</typeparam>
+        /// <param name="first">First async-enumerable sequence whose exception (if any) is caught.</param>
+        /// <param name="second">Second async-enumerable sequence used to produce results when an error occurred in the first sequence.</param>
+        /// <returns>An async-enumerable sequence containing the first sequence's elements, followed by the elements of the second sequence in case an exception occurred.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="first"/> or <paramref name="second"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Catch<TSource>(this IAsyncEnumerable<TSource> first, IAsyncEnumerable<TSource> second)
         {
             if (first == null)

Ix.NET/Source/System.Interactive.Async/System/Linq/Operators/Concat.cs

@@ -10,6 +10,13 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerableEx
     {
+        /// <summary>
+        /// Concatenates all inner async-enumerable sequences, as long as the previous async-enumerable sequence terminated successfully.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="sources">Observable sequence of inner async-enumerable sequences.</param>
+        /// <returns>An async-enumerable sequence that contains the elements of each observed inner sequence, in sequential order.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Concat<TSource>(this IAsyncEnumerable<IAsyncEnumerable<TSource>> sources)
         {
             if (sources == null)
@@ -29,6 +36,13 @@ await foreach (var item in source.WithCancellation(cancellationToken).ConfigureA
             }
         }
 
+        /// <summary>
+        /// Concatenates all async-enumerable sequences in the given enumerable sequence, as long as the previous async-enumerable sequence terminated successfully.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="sources">Observable sequences to concatenate.</param>
+        /// <returns>An async-enumerable sequence that contains the elements of each given sequence, in sequential order.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Concat<TSource>(this IEnumerable<IAsyncEnumerable<TSource>> sources)
         {
             if (sources == null)
@@ -48,6 +62,13 @@ await foreach (var item in source.WithCancellation(cancellationToken).ConfigureA
             }
         }
 
+        /// <summary>
+        /// Concatenates all of the specified async-enumerable sequences, as long as the previous async-enumerable sequence terminated successfully.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the source sequences.</typeparam>
+        /// <param name="sources">Observable sequences to concatenate.</param>
+        /// <returns>An async-enumerable sequence that contains the elements of each given sequence, in sequential order.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="sources"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Concat<TSource>(params IAsyncEnumerable<TSource>[] sources)
         {
             if (sources == null)

Ix.NET/Source/System.Interactive.Async/System/Linq/Operators/Defer.cs

@@ -10,6 +10,13 @@ namespace System.Linq
 {
     public static partial class AsyncEnumerableEx
     {
+        /// <summary>
+        /// Returns an async-enumerable sequence that invokes the specified factory function whenever a new observer subscribes.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the sequence returned by the factory function, and in the resulting sequence.</typeparam>
+        /// <param name="factory">The async-enumerable factory function to invoke for each consumer that starts enumerating the resulting asynchronous sequence.</param>
+        /// <returns>An async-enumerable sequence whose observers trigger an invocation of the given async-enumerable factory function.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="factory"/> is null.</exception>
         public static IAsyncEnumerable<TSource> Defer<TSource>(Func<IAsyncEnumerable<TSource>> factory)
         {
             if (factory == null)
@@ -26,6 +33,14 @@ await foreach (var item in factory().WithCancellation(cancellationToken).Configu
             }
         }
 
+        /// <summary>
+        /// Returns an async-enumerable sequence that starts the specified asynchronous factory function whenever a new observer subscribes.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the sequence returned by the factory function, and in the resulting sequence.</typeparam>
+        /// <param name="factory">Asynchronous factory function to start for each consumer that starts enumerating the resulting asynchronous sequence.</param>
+        /// <returns>An async-enumerable sequence whose observers trigger the given asynchronous async-enumerable factory function to be started.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="factory"/> is null.</exception>
+        /// <remarks>This operator is especially useful in conjunction with the asynchronous programming features introduced in C# 5.0 and Visual Basic 11.</remarks>
         public static IAsyncEnumerable<TSource> Defer<TSource>(Func<Task<IAsyncEnumerable<TSource>>> factory)
         {
             if (factory == null)
@@ -43,6 +58,16 @@ await foreach (var item in (await factory().ConfigureAwait(false)).WithCancellat
         }
 
 #if !NO_DEEP_CANCELLATION
+        /// <summary>
+        /// Returns an async-enumerable sequence that starts the specified cancellable asynchronous factory function whenever a new observer subscribes.
+        /// The CancellationToken passed to the asynchronous factory function is tied to the returned disposable subscription, allowing best-effort cancellation.
+        /// </summary>
+        /// <typeparam name="TSource">The type of the elements in the sequence returned by the factory function, and in the resulting sequence.</typeparam>
+        /// <param name="factory">Asynchronous factory function, supporting cancellation, to start for each consumer that starts enumerating the resulting asynchronous sequence.</param>
+        /// <returns>An async-enumerable sequence whose observers trigger the given asynchronous async-enumerable factory function to be started.</returns>
+        /// <exception cref="ArgumentNullException"><paramref name="factory"/> is null.</exception>
+        /// <remarks>This operator is especially useful in conjunction with the asynchronous programming features introduced in C# 5.0 and Visual Basic 11.</remarks>
+        /// <remarks>When a subscription to the resulting sequence is disposed, the CancellationToken that was fed to the asynchronous async-enumerable factory function will be signaled.</remarks>
         public static IAsyncEnumerable<TSource> Defer<TSource>(Func<CancellationToken, Task<IAsyncEnumerable<TSource>>> factory)
         {
             if (factory == null)