Add comments/type annotations

Author: gusty

src/FSharpPlus/Data/Seq.fs

@@ -167,6 +167,7 @@ module SeqT_V2 =
     [<Literal>]
     let private enumNotStarted = "Enumeration has not started. Call MoveNext."
 
+    /// Creates a SeqT sequence from an IEnumerableM.
     let ofIEnumerableM x : SeqT<'``Monad<bool>``, 'T> = SeqT x
 
     [<RequireQualifiedAccess; EditorBrowsable(EditorBrowsableState.Never)>]
@@ -209,6 +210,8 @@ module SeqT_V2 =
                                 dispose e1
                             | _ -> () } }
 
+    
+    /// Transforms a regular sequence into a SeqT, driven by the return type.
     let inline ofSeq (source: seq<'T>) : SeqT<'``Monad<bool>``, 'T> =
         SeqT
             { new IEnumerableM<'``Monad<bool>``, 'T> with
@@ -242,6 +245,7 @@ module SeqT_V2 =
                                 dispose e
                             | _ -> () } }
 
+    /// Transforms a regular sequence into a SeqT, driven by the return type.
     let inline hoist (source: seq<'T>) : SeqT<'``Monad<bool>``, 'T> = wrap (result source: '``Monad<seq<'T>>``)
 
     [<EditorBrowsable(EditorBrowsableState.Never)>]
@@ -342,9 +346,11 @@ module SeqT_V2 =
             { new IEnumerableM<'``Monad<bool>``, 'T> with
                 member _.GetEnumerator () = (f () :> IEnumerableM<'``Monad<bool>``, 'T>).GetEnumerator () }
 
+    /// A combination of bind and lift operations.
     let inline bindLift<'T, 'U, .. > (f: 'T -> SeqT<'``Monad<bool>``, 'U>) (source: '``Monad<'T>``) : SeqT<'``Monad<bool>``, 'U> =
         make (fun () -> innerMonad<'``Monad<SeqT<'Monad<bool>, 'U>>``> { let! v = source in return f v })
 
+    /// Lifts the source into the SeqT.
     let inline lift (source: '``Monad<'T>``) : SeqT<'``Monad<bool>``, 'T> =
         SeqT
             { new IEnumerableM<'``Monad<bool>``, 'T> with 
@@ -941,7 +947,7 @@ module SeqT_V2 =
     /// <returns>The result sequence.</returns>
     ///
     /// <exception cref="T:System.ArgumentNullException">Thrown when count is negative.</exception>
-    /// <exception cref="T:System.InvalidOperationException">Thrown when count exceeds the number of elements
+    /// <exception cref="T:System.InvalidOperationException">Thrown when count exceeds the number of elements.
     /// in the sequence.</exception>
     let inline take count (source: SeqT<'``Monad<bool>``, 'T>) : SeqT<'``Monad<bool>``, 'T> =
         if (count < 0) then invalidArg "count" "must be non-negative"

src/FSharpPlus/Data/Validation.fs

@@ -101,9 +101,15 @@ module Validation =
 
     #endif
 
-    let bimap (f: 'T1->'U1) (g: 'T2->'U2) = function
-        | Failure e -> Failure (f e)
-        | Success a -> Success (g a)
+    /// <summary>Maps both success and failure of a Validation.</summary>
+    /// <param name="failureMapper">Function to be applied to source, if it contains a Failure value.</param>
+    /// <param name="successMapper">Function to be applied to source, if it contains a Success value.</param>
+    /// <param name="source">The source value, containing a Success or a Failure.</param>
+    /// <returns>The result of applying the corresponding mapping function.</returns>
+    let bimap (failureMapper: 'TError -> 'UError) (successMapper: 'T -> 'U) source =
+        match source with
+        | Failure e -> Failure (failureMapper e)
+        | Success a -> Success (successMapper a)
 
     let bifoldBack f g (source: Validation<'Error,'T>) (state: 'State) : 'State =
         match source with
@@ -117,7 +123,7 @@ module Validation =
         | Failure e -> f e x
 
     /// Like traverse but taking an additional function to traverse the Failure part as well.
-    let inline bitraverse (f: 'Error1->'``Functor<'Error2>``) (g: 'T1->'``Functor<'T2>``) (source: Validation<'Error1,'T1>) : '``Functor<Validation<'Error2,'T2>>`` =
+    let inline bitraverse (f: 'TError -> '``Functor<'UError>``) (g: 'T -> '``Functor<'U>``) (source: Validation<'TError, 'T>) : '``Functor<Validation<'UError, 'U>>`` =
         match source with
         | Success a -> Validation<'Error2,'T2>.Success <!> g a
         | Failure e -> Validation<'Error2,'T2>.Failure <!> f e
@@ -180,11 +186,11 @@ module Validation =
     let ofChoice (x: Choice<'T,'Error>) = match x with Choice1Of2 a -> Success a | Choice2Of2 e -> Failure e
 
     /// <summary> Extracts a value from either side of a Validation.</summary>
-    /// <param name="fSuccess">Function to be applied to source, if it contains a Success value.</param>
-    /// <param name="fFailure">Function to be applied to source, if it contains a Failure value.</param>
+    /// <param name="successMapper">Function to be applied to source, if it contains a Success value.</param>
+    /// <param name="failureMapper">Function to be applied to source, if it contains a Failure value.</param>
     /// <param name="source">The source value, containing a Success or a Failure.</param>
     /// <returns>The result of applying either functions.</returns>
-    let either (fSuccess: 'T->'U) (fFailure: 'Error->'U) source = match source with Success v -> fSuccess v | Failure e -> fFailure e
+    let either (failureMapper: 'TError -> 'U) (successMapper: 'T -> 'U) source = match source with Success v -> successMapper v | Failure e -> failureMapper e
 
     [<System.Obsolete("This function will not be supported in future versions.")>]
     let validate (e: 'e) (p: 'a -> bool) (a: 'a) : Validation<'e,'a> = if p a then Success a else Failure e
@@ -193,18 +199,18 @@ module Validation =
     /// validationNel : Result<'a,'e> -> Validation (NonEmptyList<'e>) a
     /// This is 'liftError' specialized to 'NonEmptyList', since
     /// they are a common semigroup to use.
-    let validationNel (x: Result<_,_>) : (Validation<NonEmptyList<'e>,'a>) = (liftResult result) x
+    let validationNel (x: Result<'T, 'TError>) : (Validation<NonEmptyList<'TError>, 'T>) = (liftResult result) x
     #endif
 
     [<System.Obsolete("This function will not be supported in future versions.")>]
     let ensure (e: 'e) (p: 'a-> bool) = function
         | Failure x -> Failure x
         | Success a -> validate e p a
 
-    /// Creates a safe version of the supplied function, which returns a Validation<exn,'U> instead of throwing exceptions.
-    let protect (f: 'T->'U) x =
+    /// Creates a safe version of the supplied function, which returns a Validation<exn, 'U> instead of throwing exceptions.
+    let protect (unsafeFunction: 'T -> 'U) x =
         try
-            Success (f x)
+            Success (unsafeFunction x)
         with e -> Failure e
 
     #if !FABLE_COMPILER
@@ -221,7 +227,7 @@ module Validation =
     /// <returns>
     /// A tuple with both resulting lists, Success are in the first list.
     /// </returns>
-    let partition (source: list<Validation<'Error,'T>>) =
+    let partition (source: list<Validation<'TErrors, 'T>>) =
         let rec loop ((acc1, acc2) as acc) = function
             | [] -> acc
             | x::xs ->

src/FSharpPlus/Memoization.fs

@@ -20,7 +20,8 @@ module Memoization =
         static member getOrAdd (cd: ConcurrentDictionary<MemoizationKeyWrapper<'a>,'b>) (f: 'a -> 'b) k =
             cd.GetOrAdd (MemoizationKeyWrapper k, (fun (MemoizationKeyWrapper x) -> x) >> f)
 
-    let inline memoizeN (f:'``(T1 -> T2 -> ... -> Tn)``): '``(T1 -> T2 -> ... -> Tn)`` =
+    /// Memoizes a function taking an arbitrary number of parameters.
+    let inline memoizeN (f: '``(T1 -> T2 -> ... -> Tn)``) : '``(T1 -> T2 -> ... -> Tn)`` =
         let inline call_2 (a: ^MemoizeN, b: ^b) = ((^MemoizeN or ^b) : (static member MemoizeN : ^MemoizeN * 'b -> _ ) (a, b))
         call_2 (Unchecked.defaultof<MemoizeN>, Unchecked.defaultof<'``(T1 -> T2 -> ... -> Tn)``>) f
 

src/FSharpPlus/Operators.fs

@@ -984,13 +984,13 @@ module Operators =
     /// Converts to a Collection from a list.
     /// </summary>
     /// <category index="19">Collection</category>
-    let inline ofList (source: list<'T>) = OfList.Invoke source : 'Collection
+    let inline ofList (source: list<'T>) = OfList.Invoke source : '``Collection<'T>``
 
     /// <summary>
     /// Converts to a Collection from a seq.
     /// </summary>
     /// <category index="19">Collection</category>
-    let inline ofSeq (source: seq<'T> ) = OfSeq.Invoke source : 'Collection
+    let inline ofSeq (source: seq<'T> ) = OfSeq.Invoke source : '``Collection<'T>``
 
     /// <summary>Returns a new collection containing only the elements of the collection
     /// for which the given predicate returns "true"</summary>
@@ -999,7 +999,7 @@ module Operators =
     /// <param name="predicate">The function to test the input elements.</param>
     /// <param name="source">The input collection.</param>
     /// <returns>A collection containing only the elements that satisfy the predicate.</returns>
-    let inline filter (predicate: _->bool) (source: 'Collection) : 'Collection = Filter.Invoke predicate source
+    let inline filter (predicate: 'T -> bool) (source: '``Collection<'T>``) : '``Collection<'T>`` = Filter.Invoke predicate source
 
     /// <summary>Returns a collection that skips N elements of the original collection and then yields the
     /// remaining elements of the collection.</summary>