docs: document the R3 1.3.1 limitations of bind, catch and mapAsync

CHANGELOG.md

@@ -13,7 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `Observable.ofSeq (items)` and `Observable.ofSeq (items, cancellationToken)`, reachable after `open FSharp.Control.R3`
 - `Observable.chunkByBoundaries` accepting window boundaries of any element type
 - `rxqueryWith cancellationToken` and `RxQueryBuilder (cancellationToken)` to cancel the query operators that return a task
-- XML documentation for every public API
+- XML documentation for every public API, including the R3 1.3.1 limitations of `bind`, `catch` and `mapAsync`
 
 ### Changed
 

src/FSharp.Control.R3/AsyncObservable.fs

@@ -129,7 +129,21 @@ module Observable =
     /// when the source fails, with <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSwitch"/> when the next element arrives,
     /// or, with <see cref="P:FSharp.Control.R3.ProcessingOptions.CancelOnCompleted"/>, when the source completes.
     /// An exception raised by the computation is reported through <see cref="M:R3.Observer`1.OnErrorResume(System.Exception)"/>
-    /// and the sequence continues.
+    /// and the sequence continues, with these exceptions in R3 1.3.1:
+    /// </para>
+    /// <list type="bullet">
+    /// <item><description>an exception that happens after the source completed is dropped, and the sequence completes successfully without it;</description></item>
+    /// <item><description>
+    /// an <see cref="T:System.OperationCanceledException"/> is never reported: it drops the element with
+    /// <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitDrop"/>, <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSwitch"/>
+    /// and <see cref="T:FSharp.Control.R3.AwaitOperationConfiguration.AwaitParallel"/>, and stops the sequence without completing it
+    /// with the other configurations;
+    /// </description></item>
+    /// <item><description>with a limited <see cref="T:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSequentialParallel"/>, every exception permanently takes up one of the slots.</description></item>
+    /// </list>
+    /// <para>
+    /// <see cref="M:FSharp.Control.R3.Async.Observable.iterAsync``1(FSharp.Control.R3.ProcessingOptions,Microsoft.FSharp.Core.FSharpFunc{``0,Microsoft.FSharp.Control.FSharpAsync{Microsoft.FSharp.Core.Unit}},R3.Observable{``0})"/>
+    /// is not affected by these limitations.
     /// </para>
     /// </summary>
     /// <exception cref="T:System.ArgumentOutOfRangeException">Thrown when the concurrency limit of the options is 0 or below -1.</exception>

src/FSharp.Control.R3/Observable.fs

@@ -17,6 +17,10 @@ let inline asObservable source : Observable<'Source> = ObservableExtensions.AsOb
 /// The result completes when the source and every inner sequence have completed. It fails when the source fails,
 /// or when an inner sequence fails while the source is still running.
 /// </para>
+/// <para>
+/// R3 1.3.1 ignores the failure of an inner sequence that fails after the source completed: the result then completes successfully
+/// with the remaining inner sequences, or never completes when the failed one was the last one running.
+/// </para>
 /// </summary>
 let inline bind ([<InlineIfLambda>] f : 'T -> Observable<'TNext>) source = ObservableExtensions.SelectMany (source, f)
 
@@ -41,6 +45,10 @@ let inline cast<'T, 'CastType> (source) = ObservableExtensions.Cast<'T, 'CastTyp
 /// pass through without reaching the handler.
 /// A handler whose argument type is not annotated handles every exception.
 /// </para>
+/// <para>
+/// In R3 1.3.1, disposing the result after it switched to the sequence of the handler does not unsubscribe from that sequence:
+/// it stays subscribed until it completes by itself, while its elements are no longer delivered.
+/// </para>
 /// </summary>
 let inline catch ([<InlineIfLambda>] f : 'Exn -> Observable<'T>) o = ObservableExtensions.Catch (o, f)
 

src/FSharp.Control.R3/TaskObservable.fs

@@ -65,7 +65,21 @@ module Observable =
     /// when the source fails, with <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSwitch"/> when the next element arrives,
     /// or, with <see cref="P:FSharp.Control.R3.ProcessingOptions.CancelOnCompleted"/>, when the source completes.
     /// An exception of the function is reported through <see cref="M:R3.Observer`1.OnErrorResume(System.Exception)"/>
-    /// and the sequence continues.
+    /// and the sequence continues, with these exceptions in R3 1.3.1:
+    /// </para>
+    /// <list type="bullet">
+    /// <item><description>an exception that happens after the source completed is dropped, and the sequence completes successfully without it;</description></item>
+    /// <item><description>
+    /// an <see cref="T:System.OperationCanceledException"/> is never reported: it drops the element with
+    /// <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitDrop"/>, <see cref="P:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSwitch"/>
+    /// and <see cref="T:FSharp.Control.R3.AwaitOperationConfiguration.AwaitParallel"/>, and stops the sequence without completing it
+    /// with the other configurations;
+    /// </description></item>
+    /// <item><description>with a limited <see cref="T:FSharp.Control.R3.AwaitOperationConfiguration.AwaitSequentialParallel"/>, every exception permanently takes up one of the slots.</description></item>
+    /// </list>
+    /// <para>
+    /// <see cref="M:FSharp.Control.R3.Task.Observable.iterAsync``1(System.Threading.CancellationToken,FSharp.Control.R3.ProcessingOptions,Microsoft.FSharp.Core.FSharpFunc{System.Threading.CancellationToken,Microsoft.FSharp.Core.FSharpFunc{``0,System.Threading.Tasks.Task{Microsoft.FSharp.Core.Unit}}},R3.Observable{``0})"/>
+    /// is not affected by these limitations.
     /// </para>
     /// </summary>
     /// <exception cref="T:System.ArgumentOutOfRangeException">Thrown when the concurrency limit of the options is 0 or below -1.</exception>