From ee4e85125737270f8ff2f4e85da433e078a6e690 Mon Sep 17 00:00:00 2001 From: Jimmy Byrd Date: Sun, 5 Nov 2023 19:16:51 -0500 Subject: [PATCH] cleanup docs --- src/IcedTasks/CancellablePoolingValueTask.fs | 2 +- src/IcedTasks/CancellableTaskBuilderBase.fs | 86 ++++++++++---------- src/IcedTasks/TaskBuilderBase.fs | 78 +++++++++--------- tests/IcedTasks.Tests/AsyncExTests.fs | 8 +- 4 files changed, 87 insertions(+), 87 deletions(-) diff --git a/src/IcedTasks/CancellablePoolingValueTask.fs b/src/IcedTasks/CancellablePoolingValueTask.fs index f92378b..39e8828 100644 --- a/src/IcedTasks/CancellablePoolingValueTask.fs +++ b/src/IcedTasks/CancellablePoolingValueTask.fs @@ -31,7 +31,7 @@ module CancellablePoolingValueTasks = /// CancellationToken -> ValueTask type CancellableValueTask = CancellationToken -> ValueTask - /// Contains methods to build CancellableValueTasks using the F# computation expression syntax + /// Contains methods to build CancellablePoolingValueTaskBuilder using the F# computation expression syntax type CancellablePoolingValueTaskBuilder() = inherit CancellableTaskBuilderBase() diff --git a/src/IcedTasks/CancellableTaskBuilderBase.fs b/src/IcedTasks/CancellableTaskBuilderBase.fs index 6f832c8..a84ee37 100644 --- a/src/IcedTasks/CancellableTaskBuilderBase.fs +++ b/src/IcedTasks/CancellableTaskBuilderBase.fs @@ -1,6 +1,6 @@ namespace IcedTasks -/// Contains methods to build ValueTasks using the F# computation expression syntax +/// Contains methods to build CancellableTasks using the F# computation expression syntax [] module CancellableTaskBase = open System @@ -35,15 +35,15 @@ module CancellableTaskBase = and CancellableTaskBaseStateMachine<'TOverall, 'Builder> = ResumableStateMachine> - /// Represents the runtime continuation of a valueTask state machine created dynamically + /// Represents the runtime continuation of a cancellableTasks state machine created dynamically and CancellableTaskBaseResumptionFunc<'TOverall, 'Builder> = ResumptionFunc> - /// Represents the runtime continuation of a valueTask state machine created dynamically + /// Represents the runtime continuation of a cancellableTasks state machine created dynamically and CancellableTaskBaseResumptionDynamicInfo<'TOverall, 'Builder> = ResumptionDynamicInfo> - /// A special compiler-recognised delegate type for specifying blocks of valueTask code with access to the state machine + /// A special compiler-recognised delegate type for specifying blocks of cancellableTasks code with access to the state machine and CancellableTaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode, 'T> @@ -51,53 +51,53 @@ module CancellableTaskBase = /// Contains methods to build TaskLikes using the F# computation expression syntax /// type CancellableTaskBuilderBase() = - /// Creates a ValueTask that runs generator + /// Creates a CancellableTasks that runs generator /// The function to run - /// A valueTask that runs generator + /// A CancellableTasks that runs generator member inline _.Delay ([] generator: unit -> CancellableTaskBaseCode<'TOverall, 'T, 'Builder>) : CancellableTaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.Delay(fun () -> generator ()) - /// Creates an ValueTask that just returns (). + /// Creates A CancellableTasks that just returns (). /// /// The existence of this method permits the use of empty else branches in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// - /// An ValueTask that returns (). + /// A CancellableTasks that returns (). [] member inline _.Zero() : CancellableTaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.Zero() - /// Creates an computation that returns the result v. + /// Creates A Computation that returns the result v. /// /// A cancellation check is performed when the computation is executed. /// /// The existence of this method permits the use of return in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// /// The value to return from the computation. /// - /// An ValueTask that returns value when executed. + /// A cancellableTasks that returns value when executed. member inline _.Return(value: 'T) : CancellableTaskBaseCode<'T, 'T, 'Builder> = CancellableTaskBaseCode<'T, 'T, 'Builder>(fun sm -> sm.Data.Result <- value true ) - /// Creates an ValueTask that first runs task1 + /// Creates a CancellableTasks that first runs task1 /// and then runs computation2, returning the result of computation2. /// /// /// /// The existence of this method permits the use of expression sequencing in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// /// The first part of the sequenced computation. /// The second part of the sequenced computation. /// - /// An ValueTask that runs both of the computations sequentially. + /// A CancellableTasks that runs both of the computations sequentially. member inline _.Combine ( task1: CancellableTaskBaseCode<'TOverall, unit, 'Builder>, @@ -105,19 +105,19 @@ module CancellableTaskBase = ) : CancellableTaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.Combine(task1, task2) - /// Creates an ValueTask that runs computation repeatedly + /// Creates A CancellableTasks that runs computation repeatedly /// until guard() becomes false. /// /// /// /// The existence of this method permits the use of while in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// /// The function to determine when to stop executing computation. /// The function to be executed. Equivalent to the body /// of a while expression. /// - /// An ValueTask that behaves similarly to a while loop when run. + /// A CancellableTasks that behaves similarly to a while loop when run. member inline _.While ( guard: unit -> bool, @@ -125,18 +125,18 @@ module CancellableTaskBase = ) : CancellableTaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.While(guard, computation) - /// Creates an ValueTask that runs computation and returns its result. + /// Creates A CancellableTasks that runs computation and returns its result. /// If an exception happens then catchHandler(exn) is called and the resulting computation executed instead. /// /// /// /// The existence of this method permits the use of try/with in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// /// The input computation. /// The function to run when computation throws an exception. /// - /// An ValueTask that executes computation and calls catchHandler if an + /// A CancellableTasks that executes computation and calls catchHandler if an /// exception is thrown. member inline _.TryWith ( @@ -145,20 +145,20 @@ module CancellableTaskBase = ) : CancellableTaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.TryWith(computation, catchHandler) - /// Creates an ValueTask that runs computation. The action compensation is executed + /// Creates A CancellableTasks that runs computation. The action compensation is executed /// after computation completes, whether computation exits normally or by an exception. If compensation raises an exception itself /// the original exception is discarded and the new exception becomes the overall result of the computation. /// /// /// /// The existence of this method permits the use of try/finally in the - /// valueTask { ... } computation expression syntax. + /// cancellableTasks { ... } computation expression syntax. /// /// The input computation. /// The action to be run after computation completes or raises an /// exception (including cancellation). /// - /// An ValueTask that executes computation and compensation afterwards or + /// A CancellableTasks that executes computation and compensation afterwards or /// when an exception is raised. member inline _.TryFinally ( @@ -173,19 +173,19 @@ module CancellableTaskBase = ) ) - /// Creates an ValueTask that enumerates the sequence seq + /// Creates a CancellableTask that enumerates the sequence seq /// on demand and runs body for each element. /// /// A cancellation check is performed on each iteration of the loop. /// /// The existence of this method permits the use of for in the - /// valueTask { ... } computation expression syntax. + /// cancellableTask { ... } computation expression syntax. /// /// The sequence to enumerate. /// A function to take an item from the sequence and create - /// an ValueTask. Can be seen as the body of the for expression. + /// A CancellableTask. Can be seen as the body of the for expression. /// - /// An ValueTask that will enumerate the sequence and run body + /// A CancellableTask that will enumerate the sequence and run body /// for each element. member inline _.For ( @@ -194,20 +194,20 @@ module CancellableTaskBase = ) : CancellableTaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.For(sequence, body) #if NETSTANDARD2_1 || NET6_0_OR_GREATER - /// Creates an ValueTask that runs computation. The action compensation is executed + /// Creates A CancellableTask that runs computation. The action compensation is executed /// after computation completes, whether computation exits normally or by an exception. If compensation raises an exception itself /// the original exception is discarded and the new exception becomes the overall result of the computation. /// /// /// /// The existence of this method permits the use of try/finally in the - /// valueTask { ... } computation expression syntax. + /// cancellableTask { ... } computation expression syntax. /// /// The input computation. /// The action to be run after computation completes or raises an /// exception. /// - /// An ValueTask that executes computation and compensation afterwards or + /// A CancellableTask that executes computation and compensation afterwards or /// when an exception is raised. member inline internal this.TryFinallyAsync ( @@ -262,20 +262,20 @@ module CancellableTaskBase = ) ) - /// Creates an ValueTask that runs binder(resource). + /// Creates A CancellableTask that runs binder(resource). /// The action resource.DisposeAsync() is executed as this computation yields its result - /// or if the ValueTask exits by an exception or by cancellation. + /// or if the CancellableTask exits by an exception or by cancellation. /// /// /// /// The existence of this method permits the use of use and use! in the - /// valueTask { ... } computation expression syntax. + /// cancellableTask { ... } computation expression syntax. /// /// The resource to be used and disposed. /// The function that takes the resource and returns an asynchronous /// computation. /// - /// An ValueTask that binds and eventually disposes resource. + /// A CancellableTask that binds and eventually disposes resource. /// member inline this.Using ( @@ -333,7 +333,7 @@ module CancellableTaskBase = sm.ResumptionDynamicInfo.ResumptionFunc <- cont false - /// Creates an CancellableTask that runs computation, and when + /// Creates A CancellableTask that runs computation, and when /// computation generates a result T, runs binder res. /// /// A cancellation check is performed when the computation is executed. @@ -344,7 +344,7 @@ module CancellableTaskBase = /// The computation to provide an unbound result. /// The function to bind the result of computation. /// - /// An CancellableTask that performs a monadic bind on the result + /// A CancellableTask that performs a monadic bind on the result /// of computation. [] member inline _.Bind @@ -418,7 +418,7 @@ module CancellableTaskBase = sm.ResumptionDynamicInfo.ResumptionFunc <- cont false - /// Creates an CancellableTask that runs computation, and when + /// Creates A CancellableTask that runs computation, and when /// computation generates a result T, runs binder res. /// /// A cancellation check is performed when the computation is executed. @@ -429,7 +429,7 @@ module CancellableTaskBase = /// The computation to provide an unbound result. /// The function to bind the result of computation. /// - /// An CancellableTask that performs a monadic bind on the result + /// A CancellableTask that performs a monadic bind on the result /// of computation. [] member inline _.Bind @@ -573,20 +573,20 @@ module CancellableTaskBase = : CancellationToken -> 'Awaiter = (fun ct -> Awaitable.GetAwaiter(task ())) - /// Creates an ValueTask that runs binder(resource). + /// Creates A CancellableTask that runs binder(resource). /// The action resource.Dispose() is executed as this computation yields its result - /// or if the ValueTask exits by an exception or by cancellation. + /// or if the CancellableTask exits by an exception or by cancellation. /// /// /// /// The existence of this method permits the use of use and use! in the - /// valueTask { ... } computation expression syntax. + /// cancellableTask { ... } computation expression syntax. /// /// The resource to be used and disposed. /// The function that takes the resource and returns an asynchronous /// computation. /// - /// An ValueTask that binds and eventually disposes resource. + /// A CancellableTask that binds and eventually disposes resource. /// member inline _.Using ( diff --git a/src/IcedTasks/TaskBuilderBase.fs b/src/IcedTasks/TaskBuilderBase.fs index 748047c..7c95624 100644 --- a/src/IcedTasks/TaskBuilderBase.fs +++ b/src/IcedTasks/TaskBuilderBase.fs @@ -1,6 +1,6 @@ namespace IcedTasks -/// Contains methods to build ValueTasks using the F# computation expression syntax +/// Contains methods to build Tasks using the F# computation expression syntax [] module TaskBase = open System @@ -26,15 +26,15 @@ module TaskBase = and TaskBaseStateMachine<'TOverall, 'Builder> = ResumableStateMachine> - /// Represents the runtime continuation of a valueTask state machine created dynamically + /// Represents the runtime continuation of a task state machine created dynamically and TaskBaseResumptionFunc<'TOverall, 'Builder> = ResumptionFunc> - /// Represents the runtime continuation of a valueTask state machine created dynamically + /// Represents the runtime continuation of a task state machine created dynamically and TaskBaseResumptionDynamicInfo<'TOverall, 'Builder> = ResumptionDynamicInfo> - /// A special compiler-recognised delegate type for specifying blocks of valueTask code with access to the state machine + /// A special compiler-recognised delegate type for specifying blocks of task code with access to the state machine and TaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode, 'T> @@ -44,18 +44,18 @@ module TaskBase = type TaskBuilderBase() = /// Creates a ValueTask that runs generator /// The function to run - /// A valueTask that runs generator + /// A task that runs generator member inline _.Delay ([] generator: unit -> TaskBaseCode<'TOverall, 'T, 'Builder>) : TaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.Delay(fun () -> generator ()) - /// Creates an ValueTask that just returns (). + /// Creates a Task that just returns (). /// /// The existence of this method permits the use of empty else branches in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// - /// An ValueTask that returns (). + /// a Task that returns (). [] member inline _.Zero() : TaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.Zero() @@ -64,29 +64,29 @@ module TaskBase = /// A cancellation check is performed when the computation is executed. /// /// The existence of this method permits the use of return in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The value to return from the computation. /// - /// An ValueTask that returns value when executed. + /// a Task that returns value when executed. member inline _.Return(value: 'T) : TaskBaseCode<'T, 'T, 'Builder> = TaskBaseCode<'T, 'T, 'Builder>(fun sm -> sm.Data.Result <- value true ) - /// Creates an ValueTask that first runs task1 + /// Creates a Task that first runs task1 /// and then runs computation2, returning the result of computation2. /// /// /// /// The existence of this method permits the use of expression sequencing in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The first part of the sequenced computation. /// The second part of the sequenced computation. /// - /// An ValueTask that runs both of the computations sequentially. + /// a Task that runs both of the computations sequentially. member inline _.Combine ( task1: TaskBaseCode<'TOverall, unit, 'Builder>, @@ -94,19 +94,19 @@ module TaskBase = ) : TaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.Combine(task1, task2) - /// Creates an ValueTask that runs computation repeatedly + /// Creates a Task that runs computation repeatedly /// until guard() becomes false. /// /// /// /// The existence of this method permits the use of while in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The function to determine when to stop executing computation. /// The function to be executed. Equivalent to the body /// of a while expression. /// - /// An ValueTask that behaves similarly to a while loop when run. + /// a Task that behaves similarly to a while loop when run. member inline _.While ( guard: unit -> bool, @@ -114,18 +114,18 @@ module TaskBase = ) : TaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.While(guard, computation) - /// Creates an ValueTask that runs computation and returns its result. + /// Creates a Task that runs computation and returns its result. /// If an exception happens then catchHandler(exn) is called and the resulting computation executed instead. /// /// /// /// The existence of this method permits the use of try/with in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The input computation. /// The function to run when computation throws an exception. /// - /// An ValueTask that executes computation and calls catchHandler if an + /// a Task that executes computation and calls catchHandler if an /// exception is thrown. member inline _.TryWith ( @@ -134,20 +134,20 @@ module TaskBase = ) : TaskBaseCode<'TOverall, 'T, 'Builder> = ResumableCode.TryWith(computation, catchHandler) - /// Creates an ValueTask that runs computation. The action compensation is executed + /// Creates a Task that runs computation. The action compensation is executed /// after computation completes, whether computation exits normally or by an exception. If compensation raises an exception itself /// the original exception is discarded and the new exception becomes the overall result of the computation. /// /// /// /// The existence of this method permits the use of try/finally in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The input computation. /// The action to be run after computation completes or raises an /// exception (including cancellation). /// - /// An ValueTask that executes computation and compensation afterwards or + /// a Task that executes computation and compensation afterwards or /// when an exception is raised. member inline _.TryFinally ( @@ -162,19 +162,19 @@ module TaskBase = ) ) - /// Creates an ValueTask that enumerates the sequence seq + /// Creates a Task that enumerates the sequence seq /// on demand and runs body for each element. /// /// A cancellation check is performed on each iteration of the loop. /// /// The existence of this method permits the use of for in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The sequence to enumerate. /// A function to take an item from the sequence and create - /// an ValueTask. Can be seen as the body of the for expression. + /// a Task. Can be seen as the body of the for expression. /// - /// An ValueTask that will enumerate the sequence and run body + /// a Task that will enumerate the sequence and run body /// for each element. member inline _.For ( @@ -183,20 +183,20 @@ module TaskBase = ) : TaskBaseCode<'TOverall, unit, 'Builder> = ResumableCode.For(sequence, body) #if NETSTANDARD2_1 || NET6_0_OR_GREATER - /// Creates an ValueTask that runs computation. The action compensation is executed + /// Creates a Task that runs computation. The action compensation is executed /// after computation completes, whether computation exits normally or by an exception. If compensation raises an exception itself /// the original exception is discarded and the new exception becomes the overall result of the computation. /// /// /// /// The existence of this method permits the use of try/finally in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The input computation. /// The action to be run after computation completes or raises an /// exception. /// - /// An ValueTask that executes computation and compensation afterwards or + /// a Task that executes computation and compensation afterwards or /// when an exception is raised. member inline internal this.TryFinallyAsync ( @@ -248,20 +248,20 @@ module TaskBase = ) ) - /// Creates an ValueTask that runs binder(resource). + /// Creates a Task that runs binder(resource). /// The action resource.DisposeAsync() is executed as this computation yields its result /// or if the ValueTask exits by an exception or by cancellation. /// /// /// /// The existence of this method permits the use of use and use! in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The resource to be used and disposed. /// The function that takes the resource and returns an asynchronous /// computation. /// - /// An ValueTask that binds and eventually disposes resource. + /// a Task that binds and eventually disposes resource. /// member inline this.Using ( @@ -316,18 +316,18 @@ module TaskBase = sm.ResumptionDynamicInfo.ResumptionFunc <- cont false - /// Creates an ValueTask that runs computation, and when + /// Creates a Task that runs computation, and when /// computation generates a result T, runs binder res. /// /// A cancellation check is performed when the computation is executed. /// /// The existence of this method permits the use of let! in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The computation to provide an unbound result. /// The function to bind the result of computation. /// - /// An ValueTask that performs a monadic bind on the result + /// a Task that performs a monadic bind on the result /// of computation. [] member inline _.Bind @@ -380,7 +380,7 @@ module TaskBase = /// Delegates to the input computation. /// /// The existence of this method permits the use of return! in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The input computation. /// @@ -424,20 +424,20 @@ module TaskBase = Awaitable.GetAwaiter task - /// Creates an ValueTask that runs binder(resource). + /// Creates a Task that runs binder(resource). /// The action resource.Dispose() is executed as this computation yields its result /// or if the ValueTask exits by an exception or by cancellation. /// /// /// /// The existence of this method permits the use of use and use! in the - /// valueTask { ... } computation expression syntax. + /// task { ... } computation expression syntax. /// /// The resource to be used and disposed. /// The function that takes the resource and returns an asynchronous /// computation. /// - /// An ValueTask that binds and eventually disposes resource. + /// a Task that binds and eventually disposes resource. /// member inline _.Using ( diff --git a/tests/IcedTasks.Tests/AsyncExTests.fs b/tests/IcedTasks.Tests/AsyncExTests.fs index 6b05a1f..02554a0 100644 --- a/tests/IcedTasks.Tests/AsyncExTests.fs +++ b/tests/IcedTasks.Tests/AsyncExTests.fs @@ -53,7 +53,7 @@ module AsyncExTests = Expect.equal result () "Should return the data" } #if !NETSTANDARD2_0 - testCaseAsync "Can ReturnFrom an ValueTask" + testCaseAsync "Can ReturnFrom a ValueTask" <| async { let data = "foo" let inner = valueTask { return data } @@ -61,7 +61,7 @@ module AsyncExTests = let! result = outer Expect.equal result data "Should return the data" } - testCaseAsync "Can ReturnFrom an ValueTask" + testCaseAsync "Can ReturnFrom a ValueTask" <| async { let inner: ValueTask = ValueTask.CompletedTask let outer = asyncEx { return! inner } @@ -134,7 +134,7 @@ module AsyncExTests = Expect.equal result () "Should return the data" } #if !NETSTANDARD2_0 - testCaseAsync "Can bind an ValueTask" + testCaseAsync "Can bind a ValueTask" <| async { let data = "foo" let inner = valueTask { return data } @@ -148,7 +148,7 @@ module AsyncExTests = let! result = outer Expect.equal result data "Should return the data" } - testCaseAsync "Can bind an ValueTask" + testCaseAsync "Can bind a ValueTask" <| async { let inner: ValueTask = ValueTask.CompletedTask