Skip to content

Commit a07d7b0

Browse files
viceroypenguinviceroypenguin
committed
Update documentation
1 parent 724efa9 commit a07d7b0

File tree

8 files changed

+176
-111
lines changed

8 files changed

+176
-111
lines changed

‎Source/SuperLinq.Async/AssertCount.cs‎

Lines changed: 27 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -3,21 +3,37 @@ namespace SuperLinq.Async;
33
public static partial class AsyncSuperEnumerable
44
{
55
/// <summary>
6-
/// Asserts that a source sequence contains a given count of elements.
6+
/// Asserts that a source sequence contains a given count of elements.
77
/// </summary>
8-
/// <typeparam name="TSource">Type of elements in <paramref name="source"/> sequence.</typeparam>
9-
/// <param name="source">Source sequence.</param>
10-
/// <param name="count">Count to assert.</param>
8+
/// <typeparam name="TSource">
9+
/// Type of elements in <paramref name="source"/> sequence.
10+
/// </typeparam>
11+
/// <param name="source">
12+
/// Source sequence.
13+
/// </param>
14+
/// <param name="count">
15+
/// Count to assert.
16+
/// </param>
1117
/// <returns>
12-
/// Returns the original sequence as long it is contains the number of elements specified by <paramref
13-
/// name="count"/>. Otherwise it throws <see cref="ArgumentException" />.
18+
/// Returns the original sequence as long it is contains the number of elements specified by <paramref
19+
/// name="count"/>. Otherwise it throws <see cref="ArgumentException" />.
1420
/// </returns>
15-
/// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
16-
/// <exception cref="ArgumentOutOfRangeException"><paramref name="count"/> is less than <c>0</c>.</exception>
17-
/// <exception cref="ArgumentException"><paramref name="source"/> has a length different than <paramref
18-
/// name="count"/>.</exception>
21+
/// <exception cref="ArgumentNullException">
22+
/// <paramref name="source"/> is <see langword="null" />.
23+
/// </exception>
24+
/// <exception cref="ArgumentOutOfRangeException">
25+
/// <paramref name="count"/> is less than <c>0</c>.
26+
/// </exception>
27+
/// <exception cref="InvalidOperationException">
28+
/// Thrown lazily <paramref name="source"/> has a length different than <paramref name="count"/>.
29+
/// </exception>
1930
/// <remarks>
20-
/// This operator uses deferred execution and streams its results.
31+
/// <para>
32+
/// This operator uses deferred execution and streams its results.
33+
/// </para>
34+
/// <para>
35+
/// The sequence length is evaluated lazily during the enumeration of the sequence.
36+
/// </para>
2137
/// </remarks>
2238
public static IAsyncEnumerable<TSource> AssertCount<TSource>(this IAsyncEnumerable<TSource> source, int count)
2339
{

‎Source/SuperLinq.Async/Catch.cs‎

Lines changed: 83 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -3,22 +3,34 @@ namespace SuperLinq.Async;
33
public static partial class AsyncSuperEnumerable
44
{
55
/// <summary>
6-
/// Creates a sequence that corresponds to the source sequence, concatenating it with the sequence resulting from
7-
/// calling an exception handler function in case of an error.
6+
/// Creates a sequence that corresponds to the source sequence, concatenating it with the sequence resulting
7+
/// from calling an exception handler function in case of an error.
88
/// </summary>
9-
/// <typeparam name="TSource">Source sequence element type.</typeparam>
10-
/// <typeparam name="TException">Exception type to catch.</typeparam>
11-
/// <param name="source">Source sequence.</param>
12-
/// <param name="handler">Handler to invoke when an exception of the specified type occurs.</param>
13-
/// <returns>Source sequence, concatenated with an exception handler result sequence in case of an error.</returns>
14-
/// <exception cref="ArgumentNullException"><paramref name="source"/> or <paramref name="handler"/> is <see
15-
/// langword="null"/>.</exception>
9+
/// <typeparam name="TSource">
10+
/// Source sequence element type.
11+
/// </typeparam>
12+
/// <typeparam name="TException">
13+
/// Exception type to catch.
14+
/// </typeparam>
15+
/// <param name="source">
16+
/// Source sequence.
17+
/// </param>
18+
/// <param name="handler">
19+
/// Handler to invoke when an exception of the specified type occurs.
20+
/// </param>
21+
/// <returns>
22+
/// Source sequence, concatenated with an exception handler result sequence in case of an error.
23+
/// </returns>
24+
/// <exception cref="ArgumentNullException">
25+
/// <paramref name="source"/> or <paramref name="handler"/> is <see langword="null"/>.
26+
/// </exception>
1627
/// <remarks>
17-
/// This method uses deferred execution and streams its results.
28+
/// This method uses deferred execution and streams its results.
1829
/// </remarks>
1930
public static IAsyncEnumerable<TSource> Catch<TSource, TException>(
2031
this IAsyncEnumerable<TSource> source,
21-
Func<TException, IAsyncEnumerable<TSource>> handler)
32+
Func<TException, IAsyncEnumerable<TSource>> handler
33+
)
2234
where TException : Exception
2335
{
2436
ArgumentNullException.ThrowIfNull(source);
@@ -57,17 +69,26 @@ static async IAsyncEnumerable<TSource> Core(
5769
}
5870

5971
/// <summary>
60-
/// Creates a sequence that returns the elements of the first sequence, switching to the second in case of an error.
72+
/// Creates a sequence that returns the elements of the first sequence, switching to the second in case of an
73+
/// error.
6174
/// </summary>
62-
/// <typeparam name="TSource">Source sequence element type.</typeparam>
63-
/// <param name="first">First sequence.</param>
64-
/// <param name="second">Second sequence, concatenated to the result in case the first sequence completes
65-
/// exceptionally.</param>
66-
/// <returns>The first sequence, followed by the second sequence in case an error is produced.</returns>
67-
/// <exception cref="ArgumentNullException"><paramref name="first"/> or <paramref name="second"/> is <see
68-
/// langword="null"/>.</exception>
75+
/// <typeparam name="TSource">
76+
/// Source sequence element type.
77+
/// </typeparam>
78+
/// <param name="first">
79+
/// First sequence.
80+
/// </param>
81+
/// <param name="second">
82+
/// Second sequence, concatenated to the result in case the first sequence completes exceptionally.
83+
/// </param>
84+
/// <returns>
85+
/// The first sequence, followed by the second sequence in case an error is produced.
86+
/// </returns>
87+
/// <exception cref="ArgumentNullException">
88+
/// <paramref name="first"/> or <paramref name="second"/> is <see langword="null"/>.
89+
/// </exception>
6990
/// <remarks>
70-
/// This method uses deferred execution and streams its results.
91+
/// This method uses deferred execution and streams its results.
7192
/// </remarks>
7293
public static IAsyncEnumerable<TSource> Catch<TSource>(this IAsyncEnumerable<TSource> first, IAsyncEnumerable<TSource> second)
7394
{
@@ -78,14 +99,22 @@ public static IAsyncEnumerable<TSource> Catch<TSource>(this IAsyncEnumerable<TSo
7899
}
79100

80101
/// <summary>
81-
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
102+
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
82103
/// </summary>
83-
/// <typeparam name="TSource">Source sequence element type.</typeparam>
84-
/// <param name="sources">Source sequences.</param>
85-
/// <returns>Sequence that continues to concatenate source sequences while errors occur.</returns>
86-
/// <exception cref="ArgumentNullException"><paramref name="sources"/> is <see langword="null"/>.</exception>
104+
/// <typeparam name="TSource">
105+
/// Source sequence element type.
106+
/// </typeparam>
107+
/// <param name="sources">
108+
/// Source sequences.
109+
/// </param>
110+
/// <returns>
111+
/// Sequence that continues to concatenate source sequences while errors occur.
112+
/// </returns>
113+
/// <exception cref="ArgumentNullException">
114+
/// <paramref name="sources"/> is <see langword="null"/>.
115+
/// </exception>
87116
/// <remarks>
88-
/// This method uses deferred execution and streams its results.
117+
/// This method uses deferred execution and streams its results.
89118
/// </remarks>
90119
public static IAsyncEnumerable<TSource> Catch<TSource>(params IAsyncEnumerable<TSource>[] sources)
91120
{
@@ -95,14 +124,22 @@ public static IAsyncEnumerable<TSource> Catch<TSource>(params IAsyncEnumerable<T
95124
}
96125

97126
/// <summary>
98-
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
127+
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
99128
/// </summary>
100-
/// <typeparam name="TSource">Source sequence element type.</typeparam>
101-
/// <param name="sources">Source sequences.</param>
102-
/// <returns>Sequence that continues to concatenate source sequences while errors occur.</returns>
103-
/// <exception cref="ArgumentNullException"><paramref name="sources"/> is <see langword="null"/>.</exception>
129+
/// <typeparam name="TSource">
130+
/// Source sequence element type.
131+
/// </typeparam>
132+
/// <param name="sources">
133+
/// Source sequences.
134+
/// </param>
135+
/// <returns>
136+
/// Sequence that continues to concatenate source sequences while errors occur.
137+
/// </returns>
138+
/// <exception cref="ArgumentNullException">
139+
/// <paramref name="sources"/> is <see langword="null"/>.
140+
/// </exception>
104141
/// <remarks>
105-
/// This method uses deferred execution and streams its results.
142+
/// This method uses deferred execution and streams its results.
106143
/// </remarks>
107144
public static IAsyncEnumerable<TSource> Catch<TSource>(this IEnumerable<IAsyncEnumerable<TSource>> sources)
108145
{
@@ -112,14 +149,22 @@ public static IAsyncEnumerable<TSource> Catch<TSource>(this IEnumerable<IAsyncEn
112149
}
113150

114151
/// <summary>
115-
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
152+
/// Creates a sequence by concatenating source sequences until a source sequence completes successfully.
116153
/// </summary>
117-
/// <typeparam name="TSource">Source sequence element type.</typeparam>
118-
/// <param name="sources">Source sequences.</param>
119-
/// <returns>Sequence that continues to concatenate source sequences while errors occur.</returns>
120-
/// <exception cref="ArgumentNullException"><paramref name="sources"/> is <see langword="null"/>.</exception>
154+
/// <typeparam name="TSource">
155+
/// Source sequence element type.
156+
/// </typeparam>
157+
/// <param name="sources">
158+
/// Source sequences.
159+
/// </param>
160+
/// <returns>
161+
/// Sequence that continues to concatenate source sequences while errors occur.
162+
/// </returns>
163+
/// <exception cref="ArgumentNullException">
164+
/// <paramref name="sources"/> is <see langword="null"/>.
165+
/// </exception>
121166
/// <remarks>
122-
/// This method uses deferred execution and streams its results.
167+
/// This method uses deferred execution and streams its results.
123168
/// </remarks>
124169
public static IAsyncEnumerable<TSource> Catch<TSource>(this IAsyncEnumerable<IAsyncEnumerable<TSource>> sources)
125170
{

‎Source/SuperLinq.Async/Timeout.cs‎

Lines changed: 40 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -3,38 +3,52 @@ namespace SuperLinq.Async;
33
public static partial class AsyncSuperEnumerable
44
{
55
/// <summary>
6-
/// Applies a timeout policy for each element in the async-enumerable sequence. If the next element isn't received
7-
/// within the specified timeout duration, a <see cref="TimeoutException"/> is propagated to the consumer.
6+
/// Applies a timeout policy for each element in the async-enumerable sequence. If the next element isn't
7+
/// received within the specified timeout duration, a <see cref="TimeoutException"/> is propagated to the
8+
/// consumer.
89
/// </summary>
9-
/// <typeparam name="TSource">The type of the elements in the source sequence.</typeparam>
10-
/// <param name="source">Source sequence to perform a timeout for.</param>
11-
/// <param name="timeout">Maximum duration between values before a timeout occurs.</param>
12-
/// <returns>The source sequence with a <see cref="TimeoutException"/> in case of a timeout.</returns>
13-
/// <exception cref="ArgumentNullException"><paramref name="source"/> is null.</exception>
14-
/// <exception cref="ArgumentOutOfRangeException"><paramref name="timeout"/> is less than <see
15-
/// cref="TimeSpan.Zero"/>.</exception>
16-
/// <exception cref="TimeoutException">If no element is produced within <paramref name="timeout"/> from the previous
17-
/// element.</exception>
10+
/// <typeparam name="TSource">
11+
/// The type of the elements in the source sequence.
12+
/// </typeparam>
13+
/// <param name="source">
14+
/// Source sequence to perform a timeout for.
15+
/// </param>
16+
/// <param name="timeout">
17+
/// Maximum duration between values before a timeout occurs.
18+
/// </param>
19+
/// <returns>
20+
/// The source sequence with a <see cref="TimeoutException"/> in case of a timeout.
21+
/// </returns>
22+
/// <exception cref="ArgumentNullException">
23+
/// <paramref name="source"/> is <see langword="null" />.
24+
/// </exception>
25+
/// <exception cref="ArgumentOutOfRangeException">
26+
/// <paramref name="timeout"/> is less than <see cref="TimeSpan.Zero"/>.
27+
/// </exception>
28+
/// <exception cref="TimeoutException">
29+
/// If no element is produced within <paramref name="timeout"/> from the previous element.
30+
/// </exception>
1831
/// <remarks>
1932
/// <para>
20-
/// Specifying a <see cref="TimeSpan.Zero"/> value for <paramref name="timeout"/> is not recommended but supported,
21-
/// causing timeout timers to be scheduled that are due immediately. However, this doesn't guarantee a timeout will
22-
/// occur. If the iteration is synchronous, then the timeout will not be evaluated at all. Additionally, even a <see
23-
/// cref="TimeSpan.Zero"/> timeout has a minimum time to be handled, and the action to propagate a timeout may not
24-
/// execute immediately. In such cases, the next element may arrive before the scheduler gets a chance to run the
25-
/// timeout action.
33+
/// Specifying a <see cref="TimeSpan.Zero"/> value for <paramref name="timeout"/> is not recommended but
34+
/// supported, causing timeout timers to be scheduled that are due immediately. However, this doesn't guarantee
35+
/// a timeout will occur. If the iteration is synchronous, then the timeout will not be evaluated at all.
36+
/// Additionally, even a <see cref="TimeSpan.Zero"/> timeout has a minimum time to be handled, and the action to
37+
/// propagate a timeout may not execute immediately. In such cases, the next element may arrive before the
38+
/// scheduler gets a chance to run the timeout action.
2639
/// </para>
2740
/// <para>
28-
/// <b>Note</b>: If <paramref name="source"/> is completely synchronous, then the <paramref name="timeout"/> will
29-
/// not be evaluated at all. If the iteration is synchronous and takes longer than <paramref name="timeout"/>, no
30-
/// exception will be thrown.
41+
/// <b>Note</b>: If <paramref name="source"/> is completely synchronous, then the <paramref name="timeout"/>
42+
/// will not be evaluated at all. If the iteration is synchronous and takes longer than <paramref
43+
/// name="timeout"/>, no exception will be thrown.
3144
/// </para>
3245
/// <para>
33-
/// This operator does not throw immediately on the expiration of <paramref name="timeout"/>. It is a violation of
34-
/// spec to attempt to dispose or otherwise interact with an <see cref="IAsyncEnumerator{T}"/> while the <see
35-
/// cref="IAsyncEnumerator{T}.MoveNextAsync"/> task is not completed. The <see cref="CancellationToken"/> provided
36-
/// to the inner enumerable will be canceled when the <paramref name="timeout"/> is expired, but this operator will
37-
/// continue to wait until the task is complete or canceled before throwing a <see cref="TimeoutException"/>.
46+
/// This operator does not throw immediately on the expiration of <paramref name="timeout"/>. It is a violation
47+
/// of spec to attempt to dispose or otherwise interact with an <see cref="IAsyncEnumerator{T}"/> while the <see
48+
/// cref="IAsyncEnumerator{T}.MoveNextAsync"/> task is not completed. The <see cref="CancellationToken"/>
49+
/// provided to the inner enumerable will be canceled when the <paramref name="timeout"/> is expired, but this
50+
/// operator will continue to wait until the task is complete or canceled before throwing a <see
51+
/// cref="TimeoutException"/>.
3852
/// </para>
3953
/// </remarks>
4054
public static IAsyncEnumerable<TSource> Timeout<TSource>(this IAsyncEnumerable<TSource> source, TimeSpan timeout)
@@ -82,7 +96,7 @@ static async IAsyncEnumerable<TSource> Core(
8296
}
8397
}
8498

85-
var moveNext = moveNextVt.Result;
99+
var moveNext = await moveNextVt;
86100
if (!moveNext)
87101
yield break;
88102

‎Source/SuperLinq/AssertCount.cs‎

Lines changed: 6 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -24,11 +24,16 @@ public static partial class SuperEnumerable
2424
/// <exception cref="ArgumentOutOfRangeException">
2525
/// <paramref name="count"/> is less than <c>0</c>.
2626
/// </exception>
27-
/// <exception cref="ArgumentException">
27+
/// <exception cref="InvalidOperationException">
2828
/// Thrown lazily <paramref name="source"/> has a length different than <paramref name="count"/>.
2929
/// </exception>
3030
/// <remarks>
31+
/// <para>
32+
/// This operator uses deferred execution and streams its results.
33+
/// </para>
34+
/// <para>
3135
/// The sequence length is evaluated lazily during the enumeration of the sequence.
36+
/// </para>
3237
/// </remarks>
3338
public static IEnumerable<TSource> AssertCount<TSource>(this IEnumerable<TSource> source, int count)
3439
{

‎Source/SuperLinq/Case.cs‎

Lines changed: 0 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -23,10 +23,6 @@ public static partial class SuperEnumerable
2323
/// <exception cref="ArgumentNullException">
2424
/// <paramref name="selector"/> or <paramref name="sources"/> is <see langword="null"/>.
2525
/// </exception>
26-
/// <exception cref="ArgumentNullException">
27-
/// (Thrown lazily) The sequence in <paramref name="sources"/> selected by the result of <paramref
28-
/// name="selector"/> is <see langword="null"/>.
29-
/// </exception>
3026
/// <remarks>
3127
/// <para>
3228
/// <paramref name="selector"/> is not evaluated until enumeration. The value returned will be used to select a
@@ -71,10 +67,6 @@ public static IEnumerable<TResult> Case<TValue, TResult>(
7167
/// <paramref name="selector"/>, <paramref name="sources"/> or <paramref name="defaultSource"/> is <see
7268
/// langword="null"/>.
7369
/// </exception>
74-
/// <exception cref="ArgumentNullException">
75-
/// (Thrown lazily) The sequence in <paramref name="sources"/> selected by the result of <paramref
76-
/// name="selector"/> is <see langword="null"/>.
77-
/// </exception>
7870
/// <remarks>
7971
/// <para>
8072
/// <paramref name="selector"/> is not evaluated until enumeration. The value returned will be used to select a

‎Source/SuperLinq/Catch.cs‎

Lines changed: 2 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -24,16 +24,13 @@ public static partial class SuperEnumerable
2424
/// <exception cref="ArgumentNullException">
2525
/// <paramref name="source"/> or <paramref name="handler"/> is <see langword="null"/>.
2626
/// </exception>
27-
/// <exception cref="ArgumentNullException">
28-
/// (Thrown lazily) The sequence <c>errSource</c> returned by <paramref name="handler"/> is <see
29-
/// langword="null"/>.
30-
/// </exception>
3127
/// <remarks>
3228
/// This method uses deferred execution and streams its results.
3329
/// </remarks>
3430
public static IEnumerable<TSource> Catch<TSource, TException>(
3531
this IEnumerable<TSource> source,
36-
Func<TException, IEnumerable<TSource>> handler)
32+
Func<TException, IEnumerable<TSource>> handler
33+
)
3734
where TException : Exception
3835
{
3936
ArgumentNullException.ThrowIfNull(source);
@@ -115,9 +112,6 @@ public static IEnumerable<TSource> Catch<TSource>(this IEnumerable<TSource> firs
115112
/// <exception cref="ArgumentNullException">
116113
/// <paramref name="sources"/> is <see langword="null"/>.
117114
/// </exception>
118-
/// <exception cref="ArgumentNullException">
119-
/// (Thrown lazily) Any sequence <c>source</c> returned by <paramref name="sources"/> is <see langword="null"/>.
120-
/// </exception>
121115
/// <remarks>
122116
/// This method uses deferred execution and streams its results.
123117
/// </remarks>
@@ -143,9 +137,6 @@ public static IEnumerable<TSource> Catch<TSource>(params IEnumerable<TSource>[]
143137
/// <exception cref="ArgumentNullException">
144138
/// <paramref name="sources"/> is <see langword="null"/>.
145139
/// </exception>
146-
/// <exception cref="ArgumentNullException">
147-
/// (Thrown lazily) Any sequence <c>source</c> returned by <paramref name="sources"/> is <see langword="null"/>.
148-
/// </exception>
149140
/// <remarks>
150141
/// This method uses deferred execution and streams its results.
151142
/// </remarks>

0 commit comments

Comments
 (0)