Added xml comments (#268)

demystifyfp · May 28, 2024 · 6f50643 · 6f50643
1 parent 952d4ba
commit 6f50643
Show file tree

Hide file tree

Showing 9 changed files with 263 additions and 10 deletions.
diff --git a/src/FsToolkit.ErrorHandling/Async.fs b/src/FsToolkit.ErrorHandling/Async.fs
@@ -1,25 +1,56 @@
 namespace FsToolkit.ErrorHandling
 
+/// <summary>
+/// Helper functions for working with the <c>Async</c> type.
+/// </summary>
 [<RequireQualifiedAccess>]
 module Async =
 
+    /// <summary>
+    /// Converts a value to an <c>Async</c> value
+    /// </summary>
+    /// <param name="value">The value to convert to an <c>Async</c> value.</param>
+    /// <returns>The <c>Async</c> value.</returns>
     let inline singleton (value: 'value) : Async<'value> =
         value
         |> async.Return
 
+    /// <summary>
+    /// Converts a value to an <c>Async</c> value
+    /// </summary>
+    /// <param name="value">The value to convert to an <c>Async</c> value.</param>
+    /// <returns>The <c>Async</c> value.</returns>
     let inline retn (value: 'value) : Async<'value> =
         value
         |> async.Return
 
+    /// <summary>
+    /// Takes a transformation function and applies it to the value of an <c>Async</c> value.
+    /// </summary>
+    /// <param name="binder">The function to bind over the <c>Async</c> value.</param>
+    /// <param name="input">The <c>Async</c> value to bind over.</param>
+    /// <returns>The result of binding the function over the <c>Async</c> value.</returns>
     let inline bind
         ([<InlineIfLambda>] binder: 'input -> Async<'output>)
         (input: Async<'input>)
         : Async<'output> =
         async.Bind(input, binder)
 
+    /// <summary>
+    /// Applies an <c>Async</c> function to an <c>Async</c> value.
+    /// </summary>
+    /// <param name="applier">The <c>Async</c> function to apply.</param>
+    /// <param name="input">The <c>Async</c> value to apply the function to.</param>
+    /// <returns>The result of applying the function to the value.</returns>
     let inline apply (applier: Async<'input -> 'output>) (input: Async<'input>) : Async<'output> =
         bind (fun f' -> bind (fun x' -> singleton (f' x')) input) applier
 
+    /// <summary>
+    /// Applies a transformation to the value of an <c>Async</c> value to a new <c>Async</c> value using the provided function.
+    /// </summary>
+    /// <param name="mapper">The function to apply to the value of the <c>Async</c> value.</param>
+    /// <param name="input">The <c>Async</c> value to transform.</param>
+    /// <returns>The transformed <c>Async</c> value.</returns>
     let inline map
         ([<InlineIfLambda>] mapper: 'input -> 'output)
         (input: Async<'input>)
@@ -31,6 +62,13 @@ module Async =
             )
             input
 
+    /// <summary>
+    /// Applies a transformation to the values of two <c>Async</c> values to a new <c>Async</c> value using the provided function.
+    /// </summary>
+    /// <param name="mapper">The function to apply to the values of the <c>Async</c> values.</param>
+    /// <param name="input1">The first <c>Async</c> value to transform.</param>
+    /// <param name="input2">The second <c>Async</c> value to transform.</param>
+    /// <returns>The transformed <c>Async</c> value.</returns>
     let inline map2
         ([<InlineIfLambda>] mapper: 'input1 -> 'input2 -> 'output)
         (input1: Async<'input1>)
@@ -47,6 +85,14 @@ module Async =
             )
             input1
 
+    /// <summary>
+    /// Applies a transformation to the values of three <c>Async</c> values to a new <c>Async</c> value using the provided function.
+    /// </summary>
+    /// <param name="mapper">The function to apply to the values of the <c>Async</c> values.</param>
+    /// <param name="input1">The first <c>Async</c> value to transform.</param>
+    /// <param name="input2">The second <c>Async</c> value to transform.</param>
+    /// <param name="input3">The third <c>Async</c> value to transform.</param>
+    /// <returns>The transformed <c>Async</c> value.</returns>
     let inline map3
         ([<InlineIfLambda>] mapper: 'input1 -> 'input2 -> 'input3 -> 'output)
         (input1: Async<'input1>)
@@ -68,21 +114,47 @@ module Async =
             )
             input1
 
+    /// <summary>
     /// Takes two asyncs and returns a tuple of the pair
+    /// </summary>
+    /// <param name="left">The first async value.</param>
+    /// <param name="right">The second async value.</param>
+    /// <returns>The tuple of the pair.</returns>
     let inline zip (left: Async<'left>) (right: Async<'right>) : Async<'left * 'right> =
         bind (fun l -> bind (fun r -> singleton (l, r)) right) left
 
+/// <summary>
+/// Operators for working with the <c>Async</c> type.
+/// </summary>
 module AsyncOperators =
 
+    /// <summary>
+    /// Shorthand for <c>Async.map</c>
+    /// </summary>
+    /// <param name="mapper">The function to map over the <c>Async</c> value.</param>
+    /// <param name="input">The <c>Async</c> value to map over.</param>
+    /// <returns>The result of mapping the function over the <c>Async</c> value.</returns>
     let inline (<!>)
         ([<InlineIfLambda>] mapper: 'input -> 'output)
         (input: Async<'input>)
         : Async<'output> =
         Async.map mapper input
 
+    /// <summary>
+    /// Shorthand for <c>Async.apply</c>
+    /// </summary>
+    /// <param name="applier">The <c>Async</c> function to apply.</param>
+    /// <param name="input">The <c>Async</c> value to apply the function to.</param>
+    /// <returns>The result of applying the function to the value.</returns>
     let inline (<*>) (applier: Async<'input -> 'output>) (input: Async<'input>) : Async<'output> =
         Async.apply applier input
 
+    /// <summary>
+    /// Shorthand for <c>Async.bind</c>
+    /// </summary>
+    /// <param name="input">The <c>Async</c> value to bind over.</param>
+    /// <param name="binder">The function to bind over the <c>Async</c> value.</param>
+    /// <returns>The result of binding the function over the <c>Async</c> value.</returns>
     let inline (>>=)
         (input: Async<'input>)
         ([<InlineIfLambda>] binder: 'input -> Async<'output>)

diff --git a/src/FsToolkit.ErrorHandling/Option.fs b/src/FsToolkit.ErrorHandling/Option.fs
@@ -1,5 +1,8 @@
 namespace FsToolkit.ErrorHandling
 
+/// <summary>
+/// Operators for working with the <c>Option</c> type.
+/// </summary>
 [<RequireQualifiedAccess>]
 module Option =
 

diff --git a/src/FsToolkit.ErrorHandling/OptionCE.fs b/src/FsToolkit.ErrorHandling/OptionCE.fs
@@ -131,6 +131,9 @@ module OptionCE =
         /// </summary>
         member inline _.Source(vopt: 'value voption) : 'value option = Option.ofValueOption vopt
 
+    /// <summary>
+    /// The default instance of the `OptionBuilder` type.
+    /// </summary>
     let option = OptionBuilder()
 
 [<AutoOpen>]
@@ -176,8 +179,8 @@ module OptionExtensions =
         /// </summary>
         member inline _.Source(s: #seq<'value>) : #seq<'value> = s
 
-        // /// <summary>
-        // /// Method lets us transform data types into our internal representation.
-        // /// </summary>
+        /// <summary>
+        /// Method lets us transform data types into our internal representation.
+        /// </summary>
         member inline _.Source(nullable: Nullable<'value>) : 'value option =
             Option.ofNullable nullable
diff --git a/src/FsToolkit.ErrorHandling/OptionOp.fs b/src/FsToolkit.ErrorHandling/OptionOp.fs
@@ -2,8 +2,18 @@ namespace FsToolkit.ErrorHandling.Operator.Option
 
 open FsToolkit.ErrorHandling
 
+/// <summary>
+/// Operators for working with the <c>Option</c> type.
+/// </summary>
 [<AutoOpen>]
 module Option =
+
+    /// <summary>
+    /// Shorthand for <c>Option.map</c>
+    /// </summary>
+    /// <param name="input">The <c>Option</c> value to bind over.</param>
+    /// <param name="binder">The function to bind over the <c>Option</c> value.</param>
+    /// <returns>The result of binding the function over the <c>Option</c> value.</returns>
     let inline (>>=)
         (input: Option<'input>)
         ([<InlineIfLambda>] binder: 'input -> Option<'output>)

diff --git a/src/FsToolkit.ErrorHandling/Result.fs b/src/FsToolkit.ErrorHandling/Result.fs
@@ -1,5 +1,8 @@
 namespace FsToolkit.ErrorHandling
 
+/// <summary>
+/// Helper functions for working with <c>Result</c> values.
+/// </summary>
 [<RequireQualifiedAccess>]
 module Result =
 
@@ -115,7 +118,7 @@ module Result =
         | Error err -> Error(onError err)
 
     /// <summary>
-    /// Combines two <c>Result</c> values and returns a new <c>Result</c> value.
+    /// Applies a function to the value within a <c>Result</c> and returns a new <c>Result</c> with the output of the function.
     ///
     /// Documentation is found here: <href>https://demystifyfp.gitbook.io/fstoolkit-errorhandling/fstoolkit.errorhandling/result/apply</href>
     /// </summary>

diff --git a/src/FsToolkit.ErrorHandling/ResultCE.fs b/src/FsToolkit.ErrorHandling/ResultCE.fs
@@ -125,6 +125,9 @@ module ResultCE =
         /// <returns></returns>
         member inline _.Source(result: Result<'ok, 'error>) : Result<'ok, 'error> = result
 
+    /// <summary>
+    /// The <c>Result</c> computation expression.
+    /// </summary>
     let result = ResultBuilder()
 
 [<AutoOpen>]

diff --git a/src/FsToolkit.ErrorHandling/ResultOp.fs b/src/FsToolkit.ErrorHandling/ResultOp.fs
@@ -2,20 +2,42 @@ namespace FsToolkit.ErrorHandling.Operator.Result
 
 open FsToolkit.ErrorHandling
 
+/// <summary>
+/// Operators for working with the <c>Result</c> type.
+/// </summary>
 [<AutoOpen>]
 module Result =
+
+    /// <summary>
+    /// Shorthand for <c>Result.map</c>
+    /// </summary>
+    /// <param name="mapper">The function to map over the <c>Result</c> value.</param>
+    /// <param name="input">The <c>Result</c> value to map over.</param>
+    /// <returns>The result of mapping the function over the <c>Result</c> value.</returns>
     let inline (<!>)
         (([<InlineIfLambda>] mapper: 'okInput -> 'okOutput))
         (input: Result<'okInput, 'error>)
         : Result<'okOutput, 'error> =
         Result.map mapper input
 
+    /// <summary>
+    /// Shorthand for <c>Result.apply</c>
+    /// </summary>
+    /// <param name="applier">The <c>Result</c> value containing the function to apply.</param>
+    /// <param name="input">The <c>Result</c> value containing the value to apply the function to.</param>
+    /// <returns>The result of applying the function in the <c>Result</c> value to the value in the other <c>Result</c> value.</returns>
     let inline (<*>)
         (applier: Result<'okInput -> 'okOutput, 'error>)
         (input: Result<'okInput, 'error>)
         : Result<'okOutput, 'error> =
         Result.apply applier input
 
+    /// <summary>
+    /// Shorthand for <c>Result.bind</c>
+    /// </summary>
+    /// <param name="input">The <c>Result</c> value to bind over.</param>
+    /// <param name="binder">The function to bind over the <c>Result</c> value.</param>
+    /// <returns>The result of binding the function over the <c>Result</c> value.</returns>
     let inline (>>=)
         (input: Result<'input, 'error>)
         ([<InlineIfLambda>] binder: 'input -> Result<'okOutput, 'error>)