refactor: add comments

Author: artemiipatov

src/GraphBLAS-sharp.Backend/Common/ClArray.fs

@@ -328,11 +328,19 @@ module ClArray =
 
                 bitmap
 
+        /// <summary>
+        /// Gets the bitmap that indicates the first elements of the sequences of consecutive identical elements
+        /// </summary>
+        /// <param name="clContext">OpenCL context.</param>
         let firstOccurrence clContext =
             getUniqueBitmapGeneral
             <| Predicates.firstOccurrence ()
             <| clContext
 
+        /// <summary>
+        /// Gets the bitmap that indicates the last elements of the sequences of consecutive identical elements
+        /// </summary>
+        /// <param name="clContext">OpenCL context.</param>
         let lastOccurrence clContext =
             getUniqueBitmapGeneral
             <| Predicates.lastOccurrence ()
@@ -360,9 +368,19 @@ module ClArray =
 
                 result
 
+        /// <summary>
+        /// Gets the bitmap that indicates the first elements of the sequences
+        /// of consecutive identical elements from either first array or second array.
+        /// </summary>
+        /// <param name="clContext">OpenCL context.</param>
         let firstOccurrence2 clContext =
             getUniqueBitmap2General firstOccurrence clContext
 
+        /// <summary>
+        /// Gets the bitmap that indicates the last elements of the sequences
+        /// of consecutive identical elements from either first array or second array.
+        /// </summary>
+        /// <param name="clContext">OpenCL context.</param>
         let lastOccurrence2 clContext =
             getUniqueBitmap2General lastOccurrence clContext
 
@@ -436,6 +454,14 @@ module ClArray =
 
             result
 
+    /// <summary>
+    /// Maps every value from the given value array and, if the result of applying function is <c>Some</c>,
+    /// places the result to a specific position from the input array of positions.
+    /// If the result of mapping is <c>None</c>, it is just ignored.
+    /// </summary>
+    /// <param name="op">Function that maps elements from value array.</param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let private assignOption (op: Expr<'a -> 'b option>) (clContext: ClContext) workGroupSize =
 
         let assign =
@@ -474,7 +500,8 @@ module ClArray =
 
     /// <summary>
     /// Applies the given function to each element of the array.
-    /// Returns the array comprised of the results <c>x</c> for each element where the function returns <c>Some(x)</c>.
+    /// Returns the array comprised of the results <c>x</c>
+    /// for each element where the function returns <c>Some(x)</c>.
     /// </summary>
     /// <param name="predicate">The function to generate options from the elements.</param>
     /// <param name="clContext">OpenCL context.</param>
@@ -512,6 +539,14 @@ module ClArray =
 
                 Some result
 
+    /// <summary>
+    /// Maps pair of values from the given value arrays and, if the result of applying function is <c>Some</c>,
+    /// places the result to a specific position from the input array of positions.
+    /// If the result of mapping is <c>None</c>, it is just ignored.
+    /// </summary>
+    /// <param name="op">Function that maps pairs of elements from value arrays.</param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let assignOption2 (op: Expr<'a -> 'b -> 'c option>) (clContext: ClContext) workGroupSize =
 
         let assign =
@@ -559,6 +594,14 @@ module ClArray =
 
             processor.Post(Msg.CreateRunMsg<_, _>(kernel))
 
+    /// <summary>
+    /// Applies the given function to each pair of elements of the two given arrays.
+    /// Returns the array comprised of the results <c>x</c>
+    /// for each pairs where the function returns <c>Some(x)</c>.
+    /// </summary>
+    /// <param name="predicate">The function to generate options from the pairs of elements.</param>
+    /// <param name="clContext">OpenCL context.</param>
+    /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
     let choose2 (predicate: Expr<'a -> 'b -> 'c option>) (clContext: ClContext) workGroupSize =
         let getBitmap =
             map2<'a, 'b, int> (Map.choose2Bitmap predicate) clContext workGroupSize
@@ -830,7 +873,7 @@ module ClArray =
                 None
 
     let private bound<'a, 'b when 'a: equality and 'a: comparison>
-        (lowerBound: Expr<(int -> 'a -> ClArray<'a> -> 'b)>)
+        (lowerBound: Expr<int -> 'a -> ClArray<'a> -> 'b>)
         (clContext: ClContext)
         workGroupSize
         =
@@ -860,9 +903,24 @@ module ClArray =
 
             result
 
+    /// <summary>
+    /// Finds the position of the largest value and the value itself
+    /// that is less than the given one.
+    /// </summary>
+    /// <remarks>
+    /// Array of values should be sorted.
+    /// </remarks>
+    /// <param name="clContext">OpenCL context.</param>
     let upperBoundAndValue<'a when 'a: comparison> clContext =
         bound<'a, int * 'a> Search.Bin.lowerBoundAndValue clContext
 
+    /// <summary>
+    /// Finds the position of the largest value that is less than the given one.
+    /// </summary>
+    /// <remarks>
+    /// Array of values should be sorted.
+    /// </remarks>
+    /// <param name="clContext">OpenCL context.</param>
     let upperBound<'a when 'a: comparison> clContext =
         bound<'a, int> Search.Bin.lowerBound clContext
 

src/GraphBLAS-sharp.Backend/Common/Common.fs

@@ -6,11 +6,52 @@ open GraphBLAS.FSharp.Backend.Common
 
 module Common =
     module Bitonic =
+        /// <summary>
+        /// Sorts in-place input array of values by their 2d indices,
+        /// which are stored in two given arrays of keys: rows and columns.
+        /// When comparing, it first looks at rows, then columns.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// let rows = [| 0; 0; 3; 2; 1; 0; 5 |]
+        /// let columns = [| 0; 2; 1; 2; 0; 3; 5; |]
+        /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+        /// sortKeyValuesInplace clContext 32 processor rows columns values
+        /// ...
+        /// > val rows = [| 0; 0; 0; 1; 2; 3; 5 |]
+        /// > let columns = [| 0; 2; 3; 0; 2; 1; 5; |]
+        /// > val values = [| 1.9; 2.8; 6.4; 5.5; 4.6; 3.7; 7.3 |]
+        /// </code>
+        /// </example>
         let sortKeyValuesInplace = Sort.Bitonic.sortKeyValuesInplace
 
     module Radix =
+        /// <summary>
+        /// Sorts stable input array of values by given integer keys.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
+        /// let values = [| 1.9; 2.8; 3.7; 4.6; 5.5; 6.4; 7.3; |]
+        /// runByKeysStandard clContext 32 processor keys values
+        /// ...
+        /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
+        /// > val values = [| 1.9; 4.6; 5.5; 3.7; 2.8; 7.3; 6.4 |]
+        /// </code>
+        /// </example>
         let runByKeysStandard = Sort.Radix.runByKeysStandard
 
+        /// <summary>
+        /// Sorts stable input array of integer keys.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// let keys = [| 0; 4; 3; 1; 2; 6; 5 |]
+        /// standardRunKeysOnly clContext 32 processor keys
+        /// ...
+        /// > val keys = [| 0; 1; 2; 3; 4; 5; 6 |]
+        /// </code>
+        /// </example>
         let standardRunKeysOnly = Sort.Radix.standardRunKeysOnly
 
     module Gather =
@@ -53,7 +94,8 @@ module Common =
 
     module Scatter =
         /// <summary>
-        /// Creates a new array from the given one where it is indicated by the array of positions at which position in the new array
+        /// Creates a new array from the given one where it is indicated
+        /// by the array of positions at which position in the new array
         /// should be a value from the given one.
         /// </summary>
         /// <remarks>
@@ -135,18 +177,68 @@ module Common =
         let initLastOccurrence valueMap = Scatter.initLastOccurrence valueMap
 
     module PrefixSum =
+        /// <summary>
+        /// Exclude in-place prefix sum.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// let arr = [| 1; 1; 1; 1 |]
+        /// let sum = [| 0 |]
+        /// runExcludeInplace clContext workGroupSize processor arr sum (+) 0
+        /// |> ignore
+        /// ...
+        /// > val arr = [| 0; 1; 2; 3 |]
+        /// > val sum = [| 4 |]
+        /// </code>
+        /// </example>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
+        /// <param name="plus">Associative binary operation.</param>
+        /// <param name="zero">Zero element for binary operation.</param>
         let runExcludeInPlace plus = PrefixSum.runExcludeInPlace plus
 
+        /// <summary>
+        /// Include in-place prefix sum.
+        /// </summary>
+        /// <example>
+        /// <code>
+        /// let arr = [| 1; 1; 1; 1 |]
+        /// let sum = [| 0 |]
+        /// runExcludeInplace clContext workGroupSize processor arr sum (+) 0
+        /// |> ignore
+        /// ...
+        /// > val arr = [| 0; 1; 2; 3 |]
+        /// > val sum = [| 4 |]
+        /// </code>
+        /// </example>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
+        /// <param name="plus">Associative binary operation.</param>
+        /// <param name="zero">Zero element for binary operation.</param>
         let runIncludeInPlace plus = PrefixSum.runIncludeInPlace plus
 
+        /// <summary>
+        /// Exclude in-place prefix sum. Array is scanned starting from the end.
+        /// </summary>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
+        /// <param name="plus">Associative binary operation.</param>
+        /// <param name="zero">Zero element for binary operation.</param>
         let runBackwardsExcludeInPlace plus =
             PrefixSum.runBackwardsExcludeInPlace plus
 
+        /// <summary>
+        /// Include in-place prefix sum. Array is scanned starting from the end.
+        /// </summary>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
+        /// <param name="plus">Associative binary operation.</param>
+        /// <param name="zero">Zero element for binary operation.</param>
         let runBackwardsIncludeInPlace plus =
             PrefixSum.runBackwardsIncludeInPlace plus
 
         /// <summary>
-        /// Exclude inplace prefix sum.
+        /// Exclude in-place prefix sum of integer array with addition operation and start value that is equal to 0.
         /// </summary>
         /// <example>
         /// <code>
@@ -159,10 +251,8 @@ module Common =
         /// > val sum = [| 4 |]
         /// </code>
         /// </example>
-        ///<param name="clContext">ClContext.</param>
-        ///<param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
-        ///<param name="plus">Associative binary operation.</param>
-        ///<param name="zero">Zero element for binary operation.</param>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
         let standardExcludeInPlace (clContext: ClContext) workGroupSize =
 
             let scan =
@@ -173,23 +263,21 @@ module Common =
                 scan processor inputArray 0
 
         /// <summary>
-        /// Include inplace prefix sum.
+        /// Include in-place prefix sum of integer array with addition operation and start value that is equal to 0.
         /// </summary>
         /// <example>
         /// <code>
         /// let arr = [| 1; 1; 1; 1 |]
         /// let sum = [| 0 |]
-        /// runExcludeInplace clContext workGroupSize processor arr sum (+) 0
+        /// runIncludeInplace clContext workGroupSize processor arr sum (+) 0
         /// |> ignore
         /// ...
         /// > val arr = [| 1; 2; 3; 4 |]
         /// > val sum = [| 4 |]
         /// </code>
         /// </example>
-        ///<param name="clContext">ClContext.</param>
-        ///<param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
-        ///<param name="plus">Associative binary operation.</param>
-        ///<param name="zero">Zero element for binary operation.</param>
+        /// <param name="clContext">ClContext.</param>
+        /// <param name="workGroupSize">Should be a power of 2 and greater than 1.</param>
         let standardIncludeInPlace (clContext: ClContext) workGroupSize =
 
             let scan =

src/GraphBLAS-sharp.Backend/Quotes/Arithmetic.fs

@@ -3,7 +3,7 @@
 open GraphBLAS.FSharp.Objects
 
 module ArithmeticOperations =
-    let inline mkUnaryOp zero unaryOp =
+    let inline private mkUnaryOp zero unaryOp =
         <@ fun x ->
             let mutable res = zero
 
@@ -13,7 +13,7 @@ module ArithmeticOperations =
 
             if res = zero then None else Some res @>
 
-    let inline mkNumericSum zero =
+    let inline private mkNumericSum zero =
         <@ fun (x: 't option) (y: 't option) ->
             let mutable res = zero
 
@@ -25,7 +25,7 @@ module ArithmeticOperations =
 
             if res = zero then None else Some res @>
 
-    let inline mkNumericSumAtLeastOne zero =
+    let inline private mkNumericSumAtLeastOne zero =
         <@ fun (values: AtLeastOne<'t, 't>) ->
             let mutable res = zero
 
@@ -36,7 +36,7 @@ module ArithmeticOperations =
 
             if res = zero then None else Some res @>
 
-    let inline mkNumericMul zero =
+    let inline private mkNumericMul zero =
         <@ fun (x: 't option) (y: 't option) ->
             let mutable res = zero
 
@@ -46,7 +46,7 @@ module ArithmeticOperations =
 
             if res = zero then None else Some res @>
 
-    let inline mkNumericMulAtLeastOne zero =
+    let inline private mkNumericMulAtLeastOne zero =
         <@ fun (values: AtLeastOne<'t, 't>) ->
             let mutable res = zero
 
@@ -197,7 +197,7 @@ module ArithmeticOperations =
             else
                 Some result
 
-    let inline createPair zero op opQ = binOpQ zero opQ, binOp zero op
+    let inline private createPair zero op opQ = binOpQ zero opQ, binOp zero op
 
     // addition
     let intAdd = createPair 0 (+) <@ (+) @>