From 8e46833528568209900bb4730ed65c37623eea09 Mon Sep 17 00:00:00 2001 From: XperiAndri Date: Mon, 5 Oct 2026 02:12:29 +0200 Subject: [PATCH] docs(rxquery): document the query builder and every query operator Every member of `RxQueryBuilder` now has XML documentation that states what the query operator does and, for the operators that return a task, when it completes or fails; the `Builders` module is documented too. Co-Authored-By: Claude Opus 5.5 --- src/FSharp.Control.R3/Observable.fs | 57 +++++++++++++++++++++++++++++ 1 file changed, 57 insertions(+) diff --git a/src/FSharp.Control.R3/Observable.fs b/src/FSharp.Control.R3/Observable.fs index eed71cc..003921f 100644 --- a/src/FSharp.Control.R3/Observable.fs +++ b/src/FSharp.Control.R3/Observable.fs @@ -110,6 +110,7 @@ module ValueOptionExtensions = static member choose f = map f >> where ValueOption.isSome >> map ValueOption.get +/// The query builder and its instances. [] module Builders = @@ -136,54 +137,108 @@ module Builders = /// The token observed by the query operators that return a task. member _.CancellationToken = cancellationToken + /// Projects every element of the source to an observable sequence and merges the results. member _.For (s : Observable<_>, body : _ -> Observable<_>) = s.SelectMany (body) + + /// Projects every element of the query. [] member _.Select (s : Observable<_>, [] selector : _ -> _) = s.Select (selector) + + /// Keeps the elements of the query that satisfy the predicate. [] member _.Where (s : Observable<_>, [] predicate : _ -> bool) = s.Where (predicate) + + /// Keeps the elements of the query while they satisfy the predicate and completes at the first one that does not. [] member _.TakeWhile (s : Observable<_>, [] predicate : _ -> bool) = s.TakeWhile (predicate) + + /// Keeps the first count elements of the query and then completes. [] member _.Take (s : Observable<_>, count : int) = s.Take (count) + + /// Bypasses the leading elements of the query that satisfy the predicate. [] member _.SkipWhile (s : Observable<_>, [] predicate : _ -> bool) = s.SkipWhile (predicate) + + /// Bypasses the first count elements of the query. [] member _.Skip (s : Observable<_>, count : int) = s.Skip (count) + // Zero and Yield emit synchronously on subscription: scheduling them on TimeProvider.System hopped every element of // a query to the thread pool, so SelectMany merged them in arbitrary order and the results arrived late + + /// An empty sequence, used for the elements skipped by an if-then expression without else. member _.Zero () : Observable<'T> = Observable.Empty<'T>() + + /// A sequence of the single yielded element. member _.Yield (value : 'T) = Observable.Return<'T> value + + /// Counts the elements of the query. [] member _.Count (s : Observable<_>) = ObservableExtensions.CountAsync (s, cancellationToken) + + /// Determines whether every element of the query satisfies the predicate; completes at the first one that does not. [] member _.All (s : Observable<_>, [] predicate : _ -> bool) = s.AllAsync (new Func<_, bool> (predicate), cancellationToken) + + /// Determines whether the query contains the element; completes at the first equal one. [] member _.Contains (s : Observable<_>, key) = s.ContainsAsync (key, cancellationToken) + + /// Removes the repeated elements of the query. [] member _.Distinct (s : Observable<_>) = s.Distinct () + + /// Returns the only element of the query; fails when the query has no element or more than one. [] member _.ExactlyOne (s : Observable<_>) = s.SingleAsync (cancellationToken) + + /// + /// Returns the only element of the query, or the default value when the query has no element; fails on more than one. + /// The default value of a reference type is . + /// [] member _.ExactlyOneOrDefault (s : Observable<_>) = s.SingleOrDefaultAsync (cancellationToken = cancellationToken) + + /// Returns the first element of the query that satisfies the predicate; fails when there is none. [] member _.Find (s : Observable<_>, [] predicate : _ -> bool) = s.FirstAsync (new Func<_, bool> (predicate), cancellationToken) + + /// Returns the first element of the query; fails when the query has no element. [] member _.Head (s : Observable<_>) = s.FirstAsync (cancellationToken) + + /// + /// Returns the first element of the query, or the default value when the query has no element. + /// The default value of a reference type is . + /// [] member _.HeadOrDefault (s : Observable<_>) = s.FirstOrDefaultAsync (cancellationToken = cancellationToken) + + /// Returns the last element of the query; fails when the query has no element. [] member _.Last (s : Observable<_>) = s.LastAsync (cancellationToken) + + /// + /// Returns the last element of the query, or the default value when the query has no element. + /// The default value of a reference type is . + /// [] member _.LastOrDefault (s : Observable<_>) = s.LastOrDefaultAsync (cancellationToken = cancellationToken) + + /// Returns the element of the query with the largest projected value, the first one on ties; fails when the query has no element. [] member _.MaxBy (s : Observable<'a>, [] valueSelector : 'a -> 'b) = s.MaxByAsync (new Func<'a, 'b> (valueSelector), cancellationToken) + + /// Returns the element of the query with the smallest projected value, the first one on ties; fails when the query has no element. [] member _.MinBy (s : Observable<'a>, [] valueSelector : 'a -> 'b) = s.MinByAsync (new Func<'a, 'b> (valueSelector), cancellationToken) + /// Adds up the projected values of the query; returns the default value of the projected type when the query has no element. [] member inline this.SumBy (s : Observable<_>, [] valueSelector : _ -> 'Value) = // The first element seeds the sum: seeding with Unchecked.defaultof passed null to the (+) of reference types, @@ -201,10 +256,12 @@ module Builders = this.CancellationToken ) + /// Pairs the elements of the query with the elements of another sequence by position; completes with the shorter one. [] member _.Zip (s1 : Observable<_>, s2 : Observable<_>, [] resultSelector : _ -> _) = s1.Zip (s2, new Func<_, _, _> (resultSelector)) + /// Invokes the action for every element of the query; completes when the query completes. [] member _.Iter (s : Observable<_>, [] selector : _ -> _) = s.ForEachAsync (new Action<_> (selector), cancellationToken)