Merge pull request #3021 from apense/patch-7

Added some documentation and examples

lib/pure/math.nim

@@ -56,7 +56,7 @@ type
     fcNegInf     ## value is negative infinity
 
 proc classify*(x: float): FloatClass =
-  ## classifies a floating point value. Returns `x`'s class as specified by
+  ## Classifies a floating point value. Returns `x`'s class as specified by
   ## `FloatClass`.
 
   # JavaScript and most C compilers have no classify:
@@ -74,7 +74,7 @@ proc classify*(x: float): FloatClass =
 
 
 proc binom*(n, k: int): int {.noSideEffect.} =
-  ## computes the binomial coefficient
+  ## Computes the binomial coefficient
   if k <= 0: return 1
   if 2*k > n: return binom(n, n-k)
   result = n
@@ -82,18 +82,18 @@ proc binom*(n, k: int): int {.noSideEffect.} =
     result = (result * (n + 1 - i)) div i
 
 proc fac*(n: int): int {.noSideEffect.} =
-  ## computes the faculty/factorial function.
+  ## Computes the faculty/factorial function.
   result = 1
   for i in countup(2, n):
     result = result * i
 
 proc isPowerOfTwo*(x: int): bool {.noSideEffect.} =
-  ## returns true, if `x` is a power of two, false otherwise.
+  ## Returns true, if `x` is a power of two, false otherwise.
   ## Zero and negative numbers are not a power of two.
   return (x > 0) and ((x and (x - 1)) == 0)
 
 proc nextPowerOfTwo*(x: int): int {.noSideEffect.} =
-  ## returns `x` rounded up to the nearest power of two.
+  ## Returns `x` rounded up to the nearest power of two.
   ## Zero and negative numbers get rounded up to 1.
   result = x - 1
   when defined(cpu64):
@@ -108,28 +108,28 @@ proc nextPowerOfTwo*(x: int): int {.noSideEffect.} =
   result += 1 + ord(x<=0)
 
 proc countBits32*(n: int32): int {.noSideEffect.} =
-  ## counts the set bits in `n`.
+  ## Counts the set bits in `n`.
   var v = n
   v = v -% ((v shr 1'i32) and 0x55555555'i32)
   v = (v and 0x33333333'i32) +% ((v shr 2'i32) and 0x33333333'i32)
   result = ((v +% (v shr 4'i32) and 0xF0F0F0F'i32) *% 0x1010101'i32) shr 24'i32
 
 proc sum*[T](x: openArray[T]): T {.noSideEffect.} =
-  ## computes the sum of the elements in `x`.
+  ## Computes the sum of the elements in `x`.
   ## If `x` is empty, 0 is returned.
   for i in items(x): result = result + i
 
 template toFloat(f: float): float = f
 
 proc mean*[T](x: openArray[T]): float {.noSideEffect.} =
-  ## computes the mean of the elements in `x`, which are first converted to floats.
+  ## Computes the mean of the elements in `x`, which are first converted to floats.
   ## If `x` is empty, NaN is returned.
   ## ``toFloat(x: T): float`` must be defined.
   for i in items(x): result = result + toFloat(i)
   result = result / toFloat(len(x))
 
 proc variance*[T](x: openArray[T]): float {.noSideEffect.} =
-  ## computes the variance of the elements in `x`.
+  ## Computes the variance of the elements in `x`.
   ## If `x` is empty, NaN is returned.
   ## ``toFloat(x: T): float`` must be defined.
   result = 0.0
@@ -140,41 +140,43 @@ proc variance*[T](x: openArray[T]): float {.noSideEffect.} =
   result = result / toFloat(len(x))
 
 proc random*(max: int): int {.benign.}
-  ## returns a random number in the range 0..max-1. The sequence of
+  ## Returns a random number in the range 0..max-1. The sequence of
   ## random number is always the same, unless `randomize` is called
   ## which initializes the random number generator with a "random"
   ## number, i.e. a tickcount.
 
 proc random*(max: float): float {.benign.}
-  ## returns a random number in the range 0..<max. The sequence of
+  ## Returns a random number in the range 0..<max. The sequence of
   ## random number is always the same, unless `randomize` is called
   ## which initializes the random number generator with a "random"
   ## number, i.e. a tickcount. This has a 16-bit resolution on windows
   ## and a 48-bit resolution on other platforms.
 
 proc randomize*() {.benign.}
-  ## initializes the random number generator with a "random"
+  ## Initializes the random number generator with a "random"
   ## number, i.e. a tickcount. Note: Does nothing for the JavaScript target,
   ## as JavaScript does not support this.
 
 proc randomize*(seed: int) {.benign.}
-  ## initializes the random number generator with a specific seed.
+  ## Initializes the random number generator with a specific seed.
   ## Note: Does nothing for the JavaScript target,
   ## as JavaScript does not support this.
 
 {.push noSideEffect.}
 when not defined(JS):
   proc sqrt*(x: float): float {.importc: "sqrt", header: "<math.h>".}
-    ## computes the square root of `x`.
+    ## Computes the square root of `x`.
   proc cbrt*(x: float): float {.importc: "cbrt", header: "<math.h>".}
-    ## computes the cubic root of `x`
+    ## Computes the cubic root of `x`
 
   proc ln*(x: float): float {.importc: "log", header: "<math.h>".}
-    ## computes ln(x).
+    ## Computes the natural log of `x`
   proc log10*(x: float): float {.importc: "log10", header: "<math.h>".}
+    ## Computes the common logarithm (base 10) of `x`
   proc log2*(x: float): float = return ln(x) / ln(2.0)
+    ## Computes the binary logarithm (base 2) of `x`
   proc exp*(x: float): float {.importc: "exp", header: "<math.h>".}
-    ## computes e**x.
+    ## Computes the exponential function of `x` (pow(E, x))
 
   proc frexp*(x: float, exponent: var int): float {.
     importc: "frexp", header: "<math.h>".}
@@ -185,11 +187,14 @@ when not defined(JS):
     ## m.
 
   proc round*(x: float): int {.importc: "lrint", header: "<math.h>".}
-    ## converts a float to an int by rounding.
+    ## Converts a float to an int by rounding.
 
   proc arccos*(x: float): float {.importc: "acos", header: "<math.h>".}
+    ## Computes the arc cosine of `x`
   proc arcsin*(x: float): float {.importc: "asin", header: "<math.h>".}
+    ## Computes the arc sine of `x`
   proc arctan*(x: float): float {.importc: "atan", header: "<math.h>".}
+    ## Calculate the arc tangent of `y` / `x`
   proc arctan2*(y, x: float): float {.importc: "atan2", header: "<math.h>".}
     ## Calculate the arc tangent of `y` / `x`.
     ## `atan2` returns the arc tangent of `y` / `x`; it produces correct
@@ -197,16 +202,23 @@ when not defined(JS):
     ## (`x` near 0).
 
   proc cos*(x: float): float {.importc: "cos", header: "<math.h>".}
+    ## Computes the cosine of `x`
   proc cosh*(x: float): float {.importc: "cosh", header: "<math.h>".}
+    ## Computes the hyperbolic cosine of `x`
   proc hypot*(x, y: float): float {.importc: "hypot", header: "<math.h>".}
-    ## same as ``sqrt(x*x + y*y)``.
+    ## Computes the hypotenuse of a right-angle triangle with `x` and
+    ## `y` as its base and height. Equivalent to ``sqrt(x*x + y*y)``.
 
   proc sinh*(x: float): float {.importc: "sinh", header: "<math.h>".}
+    ## Computes the hyperbolic sine of `x`
   proc sin*(x: float): float {.importc: "sin", header: "<math.h>".}
+    ## Computes the sine of `x`
   proc tan*(x: float): float {.importc: "tan", header: "<math.h>".}
+    ## Computes the tangent of `x`
   proc tanh*(x: float): float {.importc: "tanh", header: "<math.h>".}
+    ## Computes the hyperbolic tangent of `x`
   proc pow*(x, y: float): float {.importc: "pow", header: "<math.h>".}
-    ## computes x to power raised of y.
+    ## Computes `x` to power of `y`.
 
   proc erf*(x: float): float {.importc: "erf", header: "<math.h>".}
     ## The error function
@@ -269,10 +281,26 @@ when not defined(JS):
     result = int(rand()) mod max
 
   proc trunc*(x: float): float {.importc: "trunc", header: "<math.h>".}
+    ## Truncates `x` to the decimal point
+    ##
+    ## .. code-block:: nim
+    ##  echo trunc(PI) # 3.0
   proc floor*(x: float): float {.importc: "floor", header: "<math.h>".}
+    ## Computes the floor function (i.e., the largest integer not greater than `x`)
+    ##
+    ## .. code-block:: nim
+    ##  echo floor(-3.5) ## -4.0
   proc ceil*(x: float): float {.importc: "ceil", header: "<math.h>".}
+    ## Computes the ceiling function (i.e., the smallest integer not less than `x`)
+    ##
+    ## .. code-block:: nim
+    ##  echo ceil(-2.1) ## -2.0
 
   proc fmod*(x, y: float): float {.importc: "fmod", header: "<math.h>".}
+    ## Computes the remainder of `x` divided by `y`
+    ##
+    ## .. code-block:: nim
+    ##  echo fmod(-2.5, 0.3) ## -0.1
 
 else:
   proc mathrandom(): float {.importc: "Math.random", nodecl.}