More docs added

docs/reference/functions/combinations.md

@@ -17,7 +17,8 @@ math.combinations(n, k)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-
+`n` | Number | BigNumber | Total number of objects in the set
+`k` | Number | BigNumber | Number of objects in the subset
 
 ### Returns
 

docs/reference/functions/concat.md

@@ -1,27 +1,47 @@
 # Function concat
 
-Concatenate two or more matrices
-Usage:
-    math.concat(A, B, C, ...)
-    math.concat(A, B, C, ..., dim)
+Concatenate two or more matrices.
 
-Where the optional dim is the zero-based number of the dimension to be
-concatenated.
 
+## Syntax
+
+```js
+math.concat(A, B, C, ...)
+math.concat(A, B, C, ..., dim)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`args` | ... Array | Matrix | 
+`args` | ... Array | Matrix | Two or more matrices
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array | Matrix | res
+Array | Matrix | Concatenated matrix
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+var A = [[1, 2], [5, 6]];
+var B = [[3, 4], [7, 8]];
+
+math.concat(A, B);      // returns [[1, 2, 3, 4], [5, 6, 7, 8]]
+math.concat(A, B, 0);   // returns [[1, 2], [5, 6], [3, 4], [7, 8]]
+```
+
+
+## See also
+
+[size](size.md),
+[squeeze](squeeze.md),
+[subset](subset.md),
+[transpose](transpose.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/det.md

@@ -1,21 +1,46 @@
 # Function det
 
+Calculate the determinant of a matrix.
 
 
+## Syntax
+
+```js
+math.det(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Array | Matrix | 
+`x` | Array | Matrix | A matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Number | determinant
+Number | The determinant of `x`
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.det([[1, 2], [3, 4]]); // returns -2
+
+var A = [
+  [-2, 2, 3],
+  [-1, 1, 3],
+  [2, 0, -1]
+]
+math.det(A); // returns 6
+```
+
+
+## See also
+
+[inv](inv.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/eye.md

@@ -1,27 +1,48 @@
 # Function eye
 
-Create a 2-dimensional identity matrix with size m x n or n x n
+Create a 2-dimensional identity matrix with size m x n or n x n.
+The matrix has ones on the diagonal and zeros elsewhere.
 
-    eye(n)
-    eye(m, n)
-    eye([m, n])
 
-TODO: more documentation on eye
+## Syntax
 
+```js
+math.eye(n)
+math.eye(m, n)
+math.eye([m, n])
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`size` | ...Number | Matrix | Array | 
+`size` | ...Number | Matrix | Array | The size for the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix | Array | Number | matrix
+Matrix | Array | Number | A matrix with ones on the diagonal.
 
 
+## Examples
+
+```js
+math.eye(3);                    // returns [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+math.eye(3, 2);                 // returns [[1, 0], [0, 1], [0, 0]]
+
+var A = [[1, 2, 3], [4, 5, 6]];
+math.eye(math.size(b));         // returns [[1, 0, 0], [0, 1, 0]]
+```
+
+
+## See also
+
+[diag](diag.md),
+[ones](ones.md),
+[zeros](zeros.md),
+[size](size.md),
+[range](range.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/inv.md

@@ -1,25 +1,40 @@
 # Function inv
 
-Calculate the inverse of a matrix
+Calculate the inverse of a square matrix.
 
-    inv(x)
 
-TODO: more documentation on inv
+## Syntax
 
+```js
+math.inv(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Number | Complex | Array | Matrix | 
+`x` | Number | Complex | Array | Matrix | Matrix to be inversed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Number | Complex | Array | Matrix | inv
+Number | Complex | Array | Matrix | The inverse of `x`.
 
 
+## Examples
+
+```js
+math.inv([[1, 2], [3, 4]]);  // returns [[-2, 1], [1.5, -0.5]]
+math.inv(4);                 // returns 0.25
+1 / 4;                       // returns 0.25
+```
+
+
+## See also
+
+[det](det.md),
+[transpose](transpose.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/max.md

@@ -1,14 +1,18 @@
 # Function max
 
-Compute the maximum value of a list of values
+Compute the maximum value of a matrix or a  list with values.
 In case of a multi dimensional array, the maximum of the flattened array
-will be calculated. When dim is provided, the maximum over the selected
-dimension will be calculated.
+will be calculated. When `dim` is provided, the maximum over the selected
+dimension will be calculated. Parameter `dim` is zero-based.
 
-    max(a, b, c, ...)
-    max(A)
-    max(A, dim)
 
+## Syntax
+
+```js
+math.max(a, b, c, ...)
+math.max(A)
+math.max(A, dim)
+```
 
 ### Parameters
 
@@ -20,9 +24,35 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-* | res
+* | The maximum value
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.max(2, 1, 4, 3);                  // returns 4
+math.max([2, 1, 4, 3]);                // returns 4
+
+// maximum over a specified dimension (zero-based)
+math.max([[2, 5], [4, 3], [1, 7]], 0); // returns [4, 7]
+math.max([[2, 5], [4, 3]], [1, 7], 1); // returns [5, 4, 7]
+
+math.max(2.7, 7.1, -4.5, 2.0, 4.1);    // returns 7.1
+math.min(2.7, 7.1, -4.5, 2.0, 4.1);    // returns -4.5
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[min](min.md),
+[prod](prod.md),
+[std](std.md),
+[sum](sum.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/mean.md

@@ -1,14 +1,18 @@
 # Function mean
 
-Compute the mean value of a list of values
+Compute the mean value of matrix or a list with values.
 In case of a multi dimensional array, the mean of the flattened array
-will be calculated. When dim is provided, the maximum over the selected
-dimension will be calculated.
+will be calculated. When `dim` is provided, the maximum over the selected
+dimension will be calculated. Parameter `dim` is zero-based.
 
-    mean(a, b, c, ...)
-    mean(A)
-    mean(A, dim)
 
+## Syntax
+
+```js
+mean.mean(a, b, c, ...)
+mean.mean(A)
+mean.mean(A, dim)
+```
 
 ### Parameters
 
@@ -20,9 +24,31 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-* | res
+* | The mean of all values
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.mean(2, 1, 4, 3);                     // returns 2.5
+math.mean([1, 2.7, 3.2, 4]);               // returns 2.725
+
+math.mean([[2, 5], [6, 3], [1, 7]], 0);    // returns [3, 5]
+math.mean([[2, 5], [6, 3], [1, 7]], 1);    // returns [3.5, 4.5, 4]
+```
+
+
+## See also
+
+[median](median.md),
+[min](min.md),
+[max](max.md),
+[sum](sum.md),
+[prod](prod.md),
+[std](std.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/median.md

@@ -1,16 +1,20 @@
 # Function median
 
-Compute the median of a list of values. The values are sorted and the
-middle value is returned. In case of an even number of values,
-the average of the two middle values is returned.
+Compute the median of a matrix or a list with values. The values are
+sorted and the middle value is returned. In case of an even number of
+values, the average of the two middle values is returned.
 Supported types of values are: Number, BigNumber, Unit
 
 In case of a (multi dimensional) array or matrix, the median of all
 elements will be calculated.
 
-    median(a, b, c, ...)
-    median(A)
 
+## Syntax
+
+```js
+mean.median(a, b, c, ...)
+mean.median(A)
+```
 
 ### Parameters
 
@@ -22,9 +26,28 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-* | res
+* | The median
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.median(5, 2, 7);        // returns 5
+math.median([3, -1, 5, 7]);  // returns 4
+```
+
+
+## See also
+
+[mean](mean.md),
+[min](min.md),
+[max](max.md),
+[sum](sum.md),
+[prod](prod.md),
+[std](std.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/min.md

@@ -1,28 +1,58 @@
 # Function min
 
-Compute the minimum value of a list of values.
-In case of a multi dimensional array, the minimum of the flattened array
-will be calculated. When dim is provided, the maximum over the selected
-dimension will be calculated.
+Compute the maximum value of a matrix or a  list of values.
+In case of a multi dimensional array, the maximum of the flattened array
+will be calculated. When `dim` is provided, the maximum over the selected
+dimension will be calculated. Parameter `dim` is zero-based.
 
-    min(a, b, c, ...)
-    min(A)
-    min(A, dim)
 
+## Syntax
+
+```js
+math.min(a, b, c, ...)
+math.min(A)
+math.min(A, dim)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`args` | ... * | A single matrix or multiple scalar values
+`args` | ... * | A single matrix or or multiple scalar values
 
 ### Returns
 
 Type | Description
 ---- | -----------
-* | res
+* | The minimum value
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.min(2, 1, 4, 3);                  // returns 1
+math.min([2, 1, 4, 3]);                // returns 1
+
+// maximum over a specified dimension (zero-based)
+math.min([[2, 5], [4, 3], [1, 7]], 0); // returns [1, 3]
+math.min([[2, 5], [4, 3], [1, 7]], 1); // returns [2, 3, 1]
+
+math.max(2.7, 7.1, -4.5, 2.0, 4.1);    // returns 7.1
+math.min(2.7, 7.1, -4.5, 2.0, 4.1);    // returns -4.5
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[max](max.md),
+[prod](prod.md),
+[std](std.md),
+[sum](sum.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/multiply.md

@@ -1,6 +1,6 @@
 # Function multiply
 
-Multiply two values, `x * y`.
+Multiply two values, `x * y`. The result is squeezed.
 For matrices, the matrix product is calculated.
 
 

docs/reference/functions/ones.md

@@ -1,26 +1,48 @@
 # Function ones
 
-Create a matrix filled with ones
+Create a matrix filled with ones. The created matrix can have one or
+multiple dimensions.
 
-    ones(m)
-    ones(m, n)
-    ones([m, n])
-    ones([m, n, p, ...])
 
+## Syntax
+
+```js
+math.ones(m)
+math.ones(m, n)
+math.ones([m, n])
+math.ones([m, n, p, ...])
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`size` | ...Number | Array | 
+`size` | ...Number | Array | The size of each dimension of the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array | Matrix | Number | matrix
+Array | Matrix | Number | A matrix filled with ones
 
 
+## Examples
+
+```js
+math.ones(3);                   // returns [1, 1, 1]
+math.ones(3, 2);                // returns [[1, 1], [1, 1], [1, 1]]
+
+var A = [[1, 2, 3], [4, 5, 6]];
+math.zeros(math.size(A));       // returns [[1, 1, 1], [1, 1, 1]]
+```
+
+
+## See also
+
+[zeros](zeros.md),
+[eye](eye.md),
+[size](size.md),
+[range](range.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/parse.md

@@ -43,7 +43,10 @@ scope.a = 5;
 code.eval(scope); // 20
 
 var nodes = math.parse(['a = 3', 'b = 4', 'a * b']);
-nodes[2].compile(math).eval(); // 12
+var scope2 = {};
+nodes.map(function(node) {
+  return node.compile(math).eval(scope2);
+});  // returns [3, 4, 12]
 ```
 
 

docs/reference/functions/prod.md

@@ -1,12 +1,16 @@
 # Function prod
 
-Compute the product of a list of values
-In case of a (multi dimensional) array or matrix, the product of all
+Compute the product of a matrix or a list with values.
+In case of a (multi dimensional) array or matrix, the sum of all
 elements will be calculated.
 
-    prod(a, b, c, ...)
-    prod(A)
 
+## Syntax
+
+```js
+math.prod(a, b, c, ...)
+math.prod(A)
+```
 
 ### Parameters
 
@@ -18,9 +22,31 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-* | res
+* | The product of all values
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.multiply(2, 3);           // returns 6
+math.prod(2, 3);               // returns 6
+math.prod(2, 3, 4);            // returns 24
+math.prod([2, 3, 4]);          // returns 24
+math.prod([[2, 5], [4, 3]]);   // returns 120
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[min](min.md),
+[max](max.md),
+[sum](sum.md),
+[std](std.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/range.md

@@ -4,37 +4,25 @@ Create an array from a range.
 By default, the range end is excluded. This can be customized by providing
 an extra parameter `includeEnd`.
 
-The method accepts the following arguments
-    range(str [, includeEnd])              Create a range from a string,
-                                           where the string contains the
-                                           start, optional step, and end,
-                                           separated by a colon.
-    range(start, end [, includeEnd])       Create a range with start and
-                                           end and a step size of 1.
-    range(start, end, step [, includeEnd]) Create a range with start, step,
-                                           and end.
 
-Where:
-    {String} str
-    {Number | BigNumber} start   Start of the range
-    {Number | BigNumber} end     End of the range, excluded by default,
-                                 included when parameter includeEnd=true
-    {Number | BigNumber} step=1  Step size.
-    {boolean} includeEnd=false   Option to specify whether to include
-                                 the end or not.
-
-Example usage:
-    math.range(2, 6);        // [2,3,4,5]
-    math.range(2, -3, -1);   // [2,1,0,-1,-2]
-    math.range('2:1:6');     // [2,3,4,5]
-    math.range(2, 6, true);  // [2,3,4,5,6]
+## Syntax
 
+```js
+range(str [, includeEnd])              // Create a range from a string,
+                                       // where the string contains the
+                                       // start, optional step, and end,
+                                       // separated by a colon.
+range(start, end [, includeEnd])       // Create a range with start and
+                                       // end and a step size of 1.
+range(start, end, step [, includeEnd]) // Create a range with start, step,
+                                       // and end.
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`args` | ...* | 
+`args` | ...* | Parameters describing the ranges `start`, `end`, and optional `step`.
 
 ### Returns
 
@@ -43,6 +31,24 @@ Type | Description
 Array | Matrix | range
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.range(2, 6);        // [2, 3, 4, 5]
+math.range(2, -3, -1);   // [2, 1, 0, -1, -2]
+math.range('2:1:6');     // [2, 3, 4, 5]
+math.range(2, 6, true);  // [2, 3, 4, 5, 6]
+```
+
+
+## See also
+
+[ones](ones.md),
+[zeros](zeros.md),
+[size](size.md),
+[subset](subset.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/size.md

@@ -1,21 +1,39 @@
 # Function size
 
-Calculate the size of a matrix or scalar
+Calculate the size of a matrix or scalar.
 
-    size(x)
 
+## Syntax
+
+```js
+math.size(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Boolean | Number | Complex | Unit | String | Array | Matrix | 
+`x` | Boolean | Number | Complex | Unit | String | Array | Matrix | A matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array | Matrix | res
+Array | Matrix | A vector with size of `x`.
+
+
+## Examples
+
+```js
+var math = mathjs();
+
+math.size(2.3);                  // returns []
+math.size('hello world');        // returns [11]
+
+var A = [[1, 2, 3], [4, 5, 6]];
+math.size(A);                    // returns [2, 3]
+math.size(math.range(1,6));      // returns [5]
+```
 
 
 

docs/reference/functions/squeeze.md

@@ -1,23 +1,47 @@
 # Function squeeze
 
-Remove singleton dimensions from a matrix
+Squeeze a matrix, remove outer singleton dimensions from a matrix.
 
-    squeeze(x)
 
+## Syntax
+
+```js
+math.squeeze(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Matrix | Array | 
+`x` | Matrix | Array | Matrix to be squeezed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix | Array | res
+Matrix | Array | Squeezed matrix
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.squeeze([3]);           // returns 3
+math.squeeze([[3]]);         // returns 3
+
+var A = math.zeros(1, 3, 2); // returns [[[0, 0], [0, 0], [0, 0]]] (size 1x3x2)
+math.squeeze(A);             // returns [[0, 0], [0, 0], [0, 0]] (size 3x2)
+
+// only outer dimensions will be squeezed, so the following B will be left as as
+var B = math.zeros(3, 1, 1); // returns [[[0]], [[0]], [[0]]] (size 3x1x1)
+math.squeeze(B);             // returns [[[0]], [[0]], [[0]]] (size 3x1x1)
+```
+
+
+## See also
+
+[subset](subset.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/std.md

@@ -1,31 +1,64 @@
 # Function std
 
-Compute the standard deviation of a list of values, defined as the
-square root of the variance: std(A) = sqrt(var(A)).
+Compute the standard deviation of a matrix or a  list with values.
+The standard deviations is defined as the square root of the variance:
+`std(A) = sqrt(var(A))`.
 In case of a (multi dimensional) array or matrix, the standard deviation
 over all elements will be calculated.
 
-    std(a, b, c, ...)
-    std(A)
-    std(A, normalization)
+Optionally, the type of normalization can be specified as second
+parameter. The parameter `normalization` can be one of the following values:
 
-Where `normalization` is a string having one of the following values:
+- 'unbiased' (default) The sum of squared errors is divided by (n - 1)
+- 'uncorrected'        The sum of squared errors is divided by n
+- 'biased'             The sum of squared errors is divided by (n + 1)
 
 
+## Syntax
+
+```js
+math.std(a, b, c, ...)
+math.std(A)
+math.std(A, normalization)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`array` | Array | Matrix | A single matrix or or multiple scalar values
-`normalization` | String |  Default value: 'unbiased' Determines how to normalize the standard deviation: - 'unbiased' (default) The sum of squared errors is divided by (n - 1) - 'uncorrected'        The sum of squared errors is divided by n - 'biased'             The sum of squared errors is divided by (n + 1)
+`array` | Array | Matrix |  A single matrix or or multiple scalar values
+`normalization` | String |  Default value: 'unbiased' Determines how to normalize the variance. Choose 'unbiased' (default), 'uncorrected', or 'biased'.
 
 ### Returns
 
 Type | Description
 ---- | -----------
-* | res
+* | The standard deviation
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.std(2, 4, 6);                     // returns 2
+math.std([2, 4, 6, 8]);                // returns 2.581988897471611
+math.std([2, 4, 6, 8], 'uncorrected'); // returns 2.23606797749979
+math.std([2, 4, 6, 8], 'biased');      // returns 2
+
+math.std([[1, 2, 3], [4, 5, 6]]);      // returns 1.8708286933869707
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[max](max.md),
+[min](min.md),
+[prod](prod.md),
+[sum](sum.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/sum.md

@@ -1,12 +1,16 @@
 # Function sum
 
-Compute the sum of a list of values
+Compute the sum of a matrix or a list with values.
 In case of a (multi dimensional) array or matrix, the sum of all
 elements will be calculated.
 
-    sum(a, b, c, ...)
-    sum(A)
 
+## Syntax
+
+```js
+math.sum(a, b, c, ...)
+math.sum(A)
+```
 
 ### Parameters
 
@@ -18,9 +22,29 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-* | res
+* | The sum of all values
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.sum(2, 1, 4, 3);               // returns 10
+math.sum([2, 1, 4, 3]);             // returns 10
+math.sum([[2, 5], [4, 3], [1, 7]]); // returns 22
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[min](min.md),
+[max](max.md),
+[prod](prod.md),
+[std](std.md),
+[var](var.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/transpose.md

@@ -1,23 +1,44 @@
 # Function transpose
 
-Create the transpose of a matrix
+Transpose a matrix. All values of the matrix are reflected over its
+main diagonal. Only two dimensional matrices are supported.
 
-    transpose(x)
 
+## Syntax
+
+```js
+math.transpose(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Array | Matrix | 
+`x` | Array | Matrix | Matrix to be transposed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array | Matrix | transpose
+Array | Matrix | The transposed matrix
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+var A = [[1, 2, 3], [4, 5, 6]];
+math.transpose(A);               // returns [[1, 4], [2, 5], [3, 6]]
+```
+
+
+## See also
+
+[diag](diag.md),
+[inv](inv.md),
+[subset](subset.md),
+[squeeze](squeeze.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/var.md

@@ -1,30 +1,65 @@
 # Function var
 
-Compute the variance of a list of values
+Compute the variance of a matrix or a  list with values.
 In case of a (multi dimensional) array or matrix, the variance over all
 elements will be calculated.
 
-    var(a, b, c, ...)
-    var(A)
-    var(A, normalization)
+Optionally, the type of normalization can be specified as second
+parameter. The parameter `normalization` can be one of the following values:
 
-Where `normalization` is a string having one of the following values:
+- 'unbiased' (default) The sum of squared errors is divided by (n - 1)
+- 'uncorrected'        The sum of squared errors is divided by n
+- 'biased'             The sum of squared errors is divided by (n + 1)
+Note that older browser may not like the variable name `var`. In that
+case, the function can be called as `math['var'](...)` instead of
+`math.var(...)`.
 
 
+## Syntax
+
+```js
+math.var(a, b, c, ...)
+math.var(A)
+math.var(A, normalization)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`array` | Array | Matrix | A single matrix or or multiple scalar values
-`normalization` | String |  Default value: 'unbiased' Determines how to normalize the variance: - 'unbiased' (default) The sum of squared errors is divided by (n - 1) - 'uncorrected'        The sum of squared errors is divided by n - 'biased'             The sum of squared errors is divided by (n + 1)
+`array` | Array | Matrix |  A single matrix or or multiple scalar values
+`normalization` | String |  Default value: 'unbiased' Determines how to normalize the variance. Choose 'unbiased' (default), 'uncorrected', or 'biased'.
 
 ### Returns
 
 Type | Description
 ---- | -----------
-* | res
+* | The variance
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.var(2, 4, 6);                     // returns 4
+math.var([2, 4, 6, 8]);                // returns 6.666666666666667
+math.var([2, 4, 6, 8], 'uncorrected'); // returns 5
+math.var([2, 4, 6, 8], 'biased');      // returns 4
+
+math.var([[1, 2, 3], [4, 5, 6]]);      // returns 3.5
+```
+
+
+## See also
+
+[mean](mean.md),
+[median](median.md),
+[max](max.md),
+[min](min.md),
+[prod](prod.md),
+[std](std.md),
+[sum](sum.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/zeros.md

@@ -1,26 +1,48 @@
 # Function zeros
 
-create a matrix filled with zeros
+Create a matrix filled with zeros. The created matrix can have one or
+multiple dimensions.
 
-    zeros(m)
-    zeros(m, n)
-    zeros([m, n])
-    zeros([m, n, p, ...])
 
+## Syntax
+
+```js
+math.zeros(m)
+math.zeros(m, n)
+math.zeros([m, n])
+math.zeros([m, n, p, ...])
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`size` | ...Number | Array | 
+`size` | ...Number | Array | The size of each dimension of the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array | Matrix | Number | matrix
+Array | Matrix | Number | A matrix filled with zeros
 
 
+## Examples
+
+```js
+math.zeros(3);                  // returns [0, 0, 0]
+math.zeros(3, 2);               // returns [[0, 0], [0, 0], [0, 0]]
+
+var A = [[1, 2, 3], [4, 5, 6]];
+math.zeros(math.size(A));       // returns [[0, 0, 0], [0, 0, 0]]
+```
+
+
+## See also
+
+[ones](ones.md),
+[eye](eye.md),
+[size](size.md),
+[range](range.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

lib/expression/docs/function/matrix/concat.js

@@ -2,17 +2,17 @@ module.exports = {
   'name': 'concat',
   'category': 'Matrix',
   'syntax': [
-    'concat(a, b, c, ...)',
-    'concat(a, b, c, ..., dim)'
+    'concat(A, B, C, ...)',
+    'concat(A, B, C, ..., dim)'
   ],
   'description': 'Concatenate matrices. By default, the matrices are concatenated by the first dimension. The dimension on which to concatenate can be provided as last argument.',
   'examples': [
-    'a = [1, 2; 5, 6]',
-    'b = [3, 4; 7, 8]',
-    'concat(a, b)',
-    '[a, b]',
-    'concat(a, b, 2)',
-    '[a; b]'
+    'A = [1, 2; 5, 6]',
+    'B = [3, 4; 7, 8]',
+    'concat(A, B)',
+    '[A, B]',
+    'concat(A, B, 1)',
+    '[A; B]'
   ],
   'seealso': [
     'det', 'diag', 'eye', 'inv', 'ones', 'range', 'size', 'squeeze', 'subset', 'transpose', 'zeros'

lib/expression/docs/function/statistics/median.js

@@ -7,7 +7,7 @@ module.exports = {
   ],
   'description': 'Compute the median of all values. The values are sorted and the middle value is returned. In case of an even number of values, the average of the two middle values is returned.',
   'examples': [
-    'median(4, 2, 7)',
+    'median(5, 2, 7)',
     'median([3, -1, 5, 7])'
   ],
   'seealso': [

lib/function/matrix/concat.js

@@ -11,16 +11,34 @@ module.exports = function (math) {
       isCollection = collection.isCollection;
 
   /**
-   * Concatenate two or more matrices
-   * Usage:
+   * Concatenate two or more matrices.
+   *
+   * Syntax:
+   *
    *     math.concat(A, B, C, ...)
    *     math.concat(A, B, C, ..., dim)
    *
-   * Where the optional dim is the zero-based number of the dimension to be
-   * concatenated.
+   * Where:
    *
-   * @param {... Array | Matrix} args
-   * @return {Array | Matrix} res
+   * - `dim` is a zero-based dimension over which to concatenate the matrices.
+   *   By default the last dimension of the matrices.
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    var A = [[1, 2], [5, 6]];
+   *    var B = [[3, 4], [7, 8]];
+   *
+   *    math.concat(A, B);      // returns [[1, 2, 3, 4], [5, 6, 7, 8]]
+   *    math.concat(A, B, 0);   // returns [[1, 2], [5, 6], [3, 4], [7, 8]]
+   *
+   * See also:
+   *
+   *    size, squeeze, subset, transpose
+   *
+   * @param {... Array | Matrix} args     Two or more matrices
+   * @return {Array | Matrix} Concatenated matrix
    */
   math.concat = function concat (args) {
     var i,

lib/function/matrix/det.js

@@ -7,13 +7,31 @@ module.exports = function (math) {
       string = util.string;
 
   /**
-   * @constructor det
-   * Calculate the determinant of a matrix
+   * Calculate the determinant of a matrix.
    *
-   *     det(x)
+   * Syntax:
    *
-   * @param {Array | Matrix} x
-   * @return {Number} determinant
+   *    math.det(x)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.det([[1, 2], [3, 4]]); // returns -2
+   *
+   *    var A = [
+   *      [-2, 2, 3],
+   *      [-1, 1, 3],
+   *      [2, 0, -1]
+   *    ]
+   *    math.det(A); // returns 6
+   *
+   * See also:
+   *
+   *    inv
+   *
+   * @param {Array | Matrix} x  A matrix
+   * @return {Number} The determinant of `x`
    */
   math.det = function det (x) {
     if (arguments.length != 1) {

lib/function/matrix/eye.js

@@ -10,16 +10,29 @@ module.exports = function (math, config) {
       isArray = Array.isArray;
 
   /**
-   * Create a 2-dimensional identity matrix with size m x n or n x n
+   * Create a 2-dimensional identity matrix with size m x n or n x n.
+   * The matrix has ones on the diagonal and zeros elsewhere.
    *
-   *     eye(n)
-   *     eye(m, n)
-   *     eye([m, n])
+   * Syntax:
    *
-   * TODO: more documentation on eye
+   *    math.eye(n)
+   *    math.eye(m, n)
+   *    math.eye([m, n])
    *
-   * @param {...Number | Matrix | Array} size
-   * @return {Matrix | Array | Number} matrix
+   * Examples:
+   *
+   *    math.eye(3);                    // returns [[1, 0, 0], [0, 1, 0], [0, 0, 1]]
+   *    math.eye(3, 2);                 // returns [[1, 0], [0, 1], [0, 0]]
+   *
+   *    var A = [[1, 2, 3], [4, 5, 6]];
+   *    math.eye(math.size(b));         // returns [[1, 0, 0], [0, 1, 0]]
+   *
+   * See also:
+   *
+   *    diag, ones, zeros, size, range
+   *
+   * @param {...Number | Matrix | Array} size   The size for the matrix
+   * @return {Matrix | Array | Number} A matrix with ones on the diagonal.
    */
   math.eye = function eye (size) {
     var args = collection.argsToArray(arguments),

lib/function/matrix/inv.js

@@ -2,18 +2,27 @@ module.exports = function (math) {
   var util = require('../../util/index'),
       string = util.string,
 
-      Matrix = require('../../type/Matrix'),
-      collection = require('../../type/collection');
+      Matrix = require('../../type/Matrix');
 
   /**
-   * Calculate the inverse of a matrix
+   * Calculate the inverse of a square matrix.
    *
-   *     inv(x)
+   * Syntax:
    *
-   * TODO: more documentation on inv
+   *     math.inv(x)
    *
-   * @param {Number | Complex | Array | Matrix} x
-   * @return {Number | Complex | Array | Matrix} inv
+   * Examples:
+   *
+   *     math.inv([[1, 2], [3, 4]]);  // returns [[-2, 1], [1.5, -0.5]]
+   *     math.inv(4);                 // returns 0.25
+   *     1 / 4;                       // returns 0.25
+   *
+   * See also:
+   *
+   *     det, transpose
+   *
+   * @param {Number | Complex | Array | Matrix} x     Matrix to be inversed
+   * @return {Number | Complex | Array | Matrix} The inverse of `x`.
    */
   math.inv = function inv (x) {
     if (arguments.length != 1) {

lib/function/matrix/ones.js

@@ -10,15 +10,30 @@ module.exports = function (math, config) {
       isArray = Array.isArray;
 
   /**
-   * Create a matrix filled with ones
+   * Create a matrix filled with ones. The created matrix can have one or
+   * multiple dimensions.
    *
-   *     ones(m)
-   *     ones(m, n)
-   *     ones([m, n])
-   *     ones([m, n, p, ...])
+   * Syntax:
    *
-   * @param {...Number | Array} size
-   * @return {Array | Matrix | Number} matrix
+   *    math.ones(m)
+   *    math.ones(m, n)
+   *    math.ones([m, n])
+   *    math.ones([m, n, p, ...])
+   *
+   * Examples:
+   *
+   *    math.ones(3);                   // returns [1, 1, 1]
+   *    math.ones(3, 2);                // returns [[1, 1], [1, 1], [1, 1]]
+   *
+   *    var A = [[1, 2, 3], [4, 5, 6]];
+   *    math.zeros(math.size(A));       // returns [[1, 1, 1], [1, 1, 1]]
+   *
+   * See also:
+   *
+   *    zeros, eye, size, range
+   *
+   * @param {...Number | Array} size    The size of each dimension of the matrix
+   * @return {Array | Matrix | Number}  A matrix filled with ones
    */
   math.ones = function ones (size) {
     var args = collection.argsToArray(arguments);

lib/function/matrix/range.js

@@ -14,18 +14,20 @@ module.exports = function (math, config) {
    * By default, the range end is excluded. This can be customized by providing
    * an extra parameter `includeEnd`.
    *
-   * The method accepts the following arguments
-   *     range(str [, includeEnd])              Create a range from a string,
-   *                                            where the string contains the
-   *                                            start, optional step, and end,
-   *                                            separated by a colon.
-   *     range(start, end [, includeEnd])       Create a range with start and
-   *                                            end and a step size of 1.
-   *     range(start, end, step [, includeEnd]) Create a range with start, step,
-   *                                            and end.
+   * Syntax:
+   *
+   *     range(str [, includeEnd])              // Create a range from a string,
+   *                                            // where the string contains the
+   *                                            // start, optional step, and end,
+   *                                            // separated by a colon.
+   *     range(start, end [, includeEnd])       // Create a range with start and
+   *                                            // end and a step size of 1.
+   *     range(start, end, step [, includeEnd]) // Create a range with start, step,
+   *                                            // and end.
    *
    * Where:
-   *     {String} str
+   *
+   *     {String} str                 A string 'start:end' or 'start:step:end'
    *     {Number | BigNumber} start   Start of the range
    *     {Number | BigNumber} end     End of the range, excluded by default,
    *                                  included when parameter includeEnd=true
@@ -33,13 +35,20 @@ module.exports = function (math, config) {
    *     {boolean} includeEnd=false   Option to specify whether to include
    *                                  the end or not.
    *
-   * Example usage:
-   *     math.range(2, 6);        // [2,3,4,5]
-   *     math.range(2, -3, -1);   // [2,1,0,-1,-2]
-   *     math.range('2:1:6');     // [2,3,4,5]
-   *     math.range(2, 6, true);  // [2,3,4,5,6]
+   * Examples:
    *
-   * @param {...*} args
+   *     var math = mathjs();
+   *
+   *     math.range(2, 6);        // [2, 3, 4, 5]
+   *     math.range(2, -3, -1);   // [2, 1, 0, -1, -2]
+   *     math.range('2:1:6');     // [2, 3, 4, 5]
+   *     math.range(2, 6, true);  // [2, 3, 4, 5, 6]
+   *
+   * See also:
+   *
+   *     ones, zeros, size, subset
+   *
+   * @param {...*} args   Parameters describing the ranges `start`, `end`, and optional `step`.
    * @return {Array | Matrix} range
    */
   math.range = function range(args) {

lib/function/matrix/size.js

@@ -14,12 +14,25 @@ module.exports = function (math, config) {
       isUnit = Unit.isUnit;
 
   /**
-   * Calculate the size of a matrix or scalar
+   * Calculate the size of a matrix or scalar.
    *
-   *     size(x)
+   * Syntax:
    *
-   * @param {Boolean | Number | Complex | Unit | String | Array | Matrix} x
-   * @return {Array | Matrix} res
+   *     math.size(x)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.size(2.3);                  // returns []
+   *     math.size('hello world');        // returns [11]
+   *
+   *     var A = [[1, 2, 3], [4, 5, 6]];
+   *     math.size(A);                    // returns [2, 3]
+   *     math.size(math.range(1,6));      // returns [5]
+   *
+   * @param {Boolean | Number | Complex | Unit | String | Array | Matrix} x  A matrix
+   * @return {Array | Matrix} A vector with size of `x`.
    */
   math.size = function size (x) {
     if (arguments.length != 1) {

lib/function/matrix/squeeze.js

@@ -8,12 +8,32 @@ module.exports = function (math) {
       isArray = Array.isArray;
 
   /**
-   * Remove singleton dimensions from a matrix
+   * Squeeze a matrix, remove outer singleton dimensions from a matrix.
    *
-   *     squeeze(x)
+   * Syntax:
    *
-   * @param {Matrix | Array} x
-   * @return {Matrix | Array} res
+   *     math.squeeze(x)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.squeeze([3]);           // returns 3
+   *     math.squeeze([[3]]);         // returns 3
+   *
+   *     var A = math.zeros(1, 3, 2); // returns [[[0, 0], [0, 0], [0, 0]]] (size 1x3x2)
+   *     math.squeeze(A);             // returns [[0, 0], [0, 0], [0, 0]] (size 3x2)
+   *
+   *     // only outer dimensions will be squeezed, so the following B will be left as as
+   *     var B = math.zeros(3, 1, 1); // returns [[[0]], [[0]], [[0]]] (size 3x1x1)
+   *     math.squeeze(B);             // returns [[[0]], [[0]], [[0]]] (size 3x1x1)
+   *
+   * See also:
+   *
+   *     subset
+   *
+   * @param {Matrix | Array} x      Matrix to be squeezed
+   * @return {Matrix | Array} Squeezed matrix
    */
   math.squeeze = function squeeze (x) {
     if (arguments.length != 1) {

lib/function/matrix/transpose.js

@@ -2,18 +2,31 @@ module.exports = function (math) {
   var util = require('../../util/index'),
 
       Matrix = require('../../type/Matrix'),
-      collection = require('../../type/collection'),
 
       object = util.object,
       string = util.string;
 
   /**
-   * Create the transpose of a matrix
+   * Transpose a matrix. All values of the matrix are reflected over its
+   * main diagonal. Only two dimensional matrices are supported.
    *
-   *     transpose(x)
+   * Syntax:
    *
-   * @param {Array | Matrix} x
-   * @return {Array | Matrix} transpose
+   *     math.transpose(x)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     var A = [[1, 2, 3], [4, 5, 6]];
+   *     math.transpose(A);               // returns [[1, 4], [2, 5], [3, 6]]
+   *
+   * See also:
+   *
+   *     diag, inv, subset, squeeze
+   *
+   * @param {Array | Matrix} x  Matrix to be transposed
+   * @return {Array | Matrix}   The transposed matrix
    */
   math.transpose = function transpose (x) {
     if (arguments.length != 1) {

lib/function/matrix/zeros.js

@@ -9,15 +9,30 @@ module.exports = function (math, config) {
       isArray = Array.isArray;
 
   /**
-   * create a matrix filled with zeros
+   * Create a matrix filled with zeros. The created matrix can have one or
+   * multiple dimensions.
    *
-   *     zeros(m)
-   *     zeros(m, n)
-   *     zeros([m, n])
-   *     zeros([m, n, p, ...])
+   * Syntax:
    *
-   * @param {...Number | Array} size
-   * @return {Array | Matrix | Number} matrix
+   *    math.zeros(m)
+   *    math.zeros(m, n)
+   *    math.zeros([m, n])
+   *    math.zeros([m, n, p, ...])
+   *
+   * Examples:
+   *
+   *    math.zeros(3);                  // returns [0, 0, 0]
+   *    math.zeros(3, 2);               // returns [[0, 0], [0, 0], [0, 0]]
+   *
+   *    var A = [[1, 2, 3], [4, 5, 6]];
+   *    math.zeros(math.size(A));       // returns [[0, 0, 0], [0, 0, 0]]
+   *
+   * See also:
+   *
+   *    ones, eye, size, range
+   *
+   * @param {...Number | Array} size    The size of each dimension of the matrix
+   * @return {Array | Matrix | Number}  A matrix filled with zeros
    */
   math.zeros = function zeros (size) {
     var args = collection.argsToArray(arguments);

lib/function/probability/combinations.js

@@ -28,9 +28,9 @@ module.exports = function (math) {
    *
    *    permutations, factorial
    *
-   * @Param {Number | BigNumber} n    Total number of objects in the set
-   * @Param {Number | BigNumber} k    Number of objects in the subset
-   * @return {Number | BigNumber} Number of possible combinations.
+   * @param {Number | BigNumber} n    Total number of objects in the set
+   * @param {Number | BigNumber} k    Number of objects in the subset
+   * @return {Number | BigNumber}     Number of possible combinations.
    */
   math.combinations = function combinations (n, k) {
     var max, result, i,ii;

lib/function/statistics/max.js

@@ -5,17 +5,37 @@ module.exports = function (math) {
       isCollection = collection.isCollection;
 
   /**
-   * Compute the maximum value of a list of values
+   * Compute the maximum value of a matrix or a  list with values.
    * In case of a multi dimensional array, the maximum of the flattened array
-   * will be calculated. When dim is provided, the maximum over the selected
-   * dimension will be calculated.
+   * will be calculated. When `dim` is provided, the maximum over the selected
+   * dimension will be calculated. Parameter `dim` is zero-based.
    *
-   *     max(a, b, c, ...)
-   *     max(A)
-   *     max(A, dim)
+   * Syntax:
+   *
+   *     math.max(a, b, c, ...)
+   *     math.max(A)
+   *     math.max(A, dim)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.max(2, 1, 4, 3);                  // returns 4
+   *     math.max([2, 1, 4, 3]);                // returns 4
+   *
+   *     // maximum over a specified dimension (zero-based)
+   *     math.max([[2, 5], [4, 3], [1, 7]], 0); // returns [4, 7]
+   *     math.max([[2, 5], [4, 3]], [1, 7], 1); // returns [5, 4, 7]
+   *
+   *     math.max(2.7, 7.1, -4.5, 2.0, 4.1);    // returns 7.1
+   *     math.min(2.7, 7.1, -4.5, 2.0, 4.1);    // returns -4.5
+   *
+   * See also:
+   *
+   *    mean, median, min, prod, std, sum, var
    *
    * @param {... *} args  A single matrix or or multiple scalar values
-   * @return {*} res
+   * @return {*} The maximum value
    */
   math.max = function max(args) {
     if (arguments.length == 0) {

lib/function/statistics/mean.js

@@ -7,17 +7,33 @@ module.exports = function (math) {
       size = require('../../util/array').size;
 
   /**
-   * Compute the mean value of a list of values
+   * Compute the mean value of matrix or a list with values.
    * In case of a multi dimensional array, the mean of the flattened array
-   * will be calculated. When dim is provided, the maximum over the selected
-   * dimension will be calculated.
+   * will be calculated. When `dim` is provided, the maximum over the selected
+   * dimension will be calculated. Parameter `dim` is zero-based.
    *
-   *     mean(a, b, c, ...)
-   *     mean(A)
-   *     mean(A, dim)
+   * Syntax:
+   *
+   *     mean.mean(a, b, c, ...)
+   *     mean.mean(A)
+   *     mean.mean(A, dim)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.mean(2, 1, 4, 3);                     // returns 2.5
+   *     math.mean([1, 2.7, 3.2, 4]);               // returns 2.725
+   *
+   *     math.mean([[2, 5], [6, 3], [1, 7]], 0);    // returns [3, 5]
+   *     math.mean([[2, 5], [6, 3], [1, 7]], 1);    // returns [3.5, 4.5, 4]
+   *
+   * See also:
+   *
+   *     median, min, max, sum, prod, std, var
    *
    * @param {... *} args  A single matrix or or multiple scalar values
-   * @return {*} res
+   * @return {*} The mean of all values
    */
   math.mean = function mean(args) {
     if (arguments.length == 0) {

lib/function/statistics/median.js

@@ -10,19 +10,32 @@ module.exports = function (math) {
       flatten = require('../../util/array').flatten;
 
   /**
-   * Compute the median of a list of values. The values are sorted and the
-   * middle value is returned. In case of an even number of values,
-   * the average of the two middle values is returned.
+   * Compute the median of a matrix or a list with values. The values are
+   * sorted and the middle value is returned. In case of an even number of
+   * values, the average of the two middle values is returned.
    * Supported types of values are: Number, BigNumber, Unit
    *
    * In case of a (multi dimensional) array or matrix, the median of all
    * elements will be calculated.
    *
-   *     median(a, b, c, ...)
-   *     median(A)
+   * Syntax:
+   *
+   *     mean.median(a, b, c, ...)
+   *     mean.median(A)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.median(5, 2, 7);        // returns 5
+   *     math.median([3, -1, 5, 7]);  // returns 4
+   *
+   * See also:
+   *
+   *     mean, min, max, sum, prod, std, var
    *
    * @param {... *} args  A single matrix or or multiple scalar values
-   * @return {*} res
+   * @return {*} The median
    */
   math.median = function median(args) {
     if (arguments.length == 0) {

lib/function/statistics/min.js

@@ -5,17 +5,37 @@ module.exports = function (math) {
       isCollection = collection.isCollection;
 
   /**
-   * Compute the minimum value of a list of values.
-   * In case of a multi dimensional array, the minimum of the flattened array
-   * will be calculated. When dim is provided, the maximum over the selected
-   * dimension will be calculated.
+   * Compute the maximum value of a matrix or a  list of values.
+   * In case of a multi dimensional array, the maximum of the flattened array
+   * will be calculated. When `dim` is provided, the maximum over the selected
+   * dimension will be calculated. Parameter `dim` is zero-based.
    *
-   *     min(a, b, c, ...)
-   *     min(A)
-   *     min(A, dim)
+   * Syntax:
    *
-   * @param {... *} args  A single matrix or multiple scalar values
-   * @return {*} res
+   *     math.min(a, b, c, ...)
+   *     math.min(A)
+   *     math.min(A, dim)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.min(2, 1, 4, 3);                  // returns 1
+   *     math.min([2, 1, 4, 3]);                // returns 1
+   *
+   *     // maximum over a specified dimension (zero-based)
+   *     math.min([[2, 5], [4, 3], [1, 7]], 0); // returns [1, 3]
+   *     math.min([[2, 5], [4, 3], [1, 7]], 1); // returns [2, 3, 1]
+   *
+   *     math.max(2.7, 7.1, -4.5, 2.0, 4.1);    // returns 7.1
+   *     math.min(2.7, 7.1, -4.5, 2.0, 4.1);    // returns -4.5
+   *
+   * See also:
+   *
+   *    mean, median, max, prod, std, sum, var
+   *
+   * @param {... *} args  A single matrix or or multiple scalar values
+   * @return {*} The minimum value
    */
   math.min = function min(args) {
     if (arguments.length == 0) {

lib/function/statistics/prod.js

@@ -5,15 +5,31 @@ module.exports = function (math) {
       isCollection = collection.isCollection;
 
   /**
-   * Compute the product of a list of values
-   * In case of a (multi dimensional) array or matrix, the product of all
+   * Compute the product of a matrix or a list with values.
+   * In case of a (multi dimensional) array or matrix, the sum of all
    * elements will be calculated.
    *
-   *     prod(a, b, c, ...)
-   *     prod(A)
+   * Syntax:
+   *
+   *     math.prod(a, b, c, ...)
+   *     math.prod(A)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.multiply(2, 3);           // returns 6
+   *     math.prod(2, 3);               // returns 6
+   *     math.prod(2, 3, 4);            // returns 24
+   *     math.prod([2, 3, 4]);          // returns 24
+   *     math.prod([[2, 5], [4, 3]]);   // returns 120
+   *
+   * See also:
+   *
+   *    mean, median, min, max, sum, std, var
    *
    * @param {... *} args  A single matrix or or multiple scalar values
-   * @return {*} res
+   * @return {*} The product of all values
    */
   math.prod = function prod(args) {
     if (arguments.length == 0) {

lib/function/statistics/std.js

@@ -1,23 +1,47 @@
 module.exports = function (math) {
+
+
   /**
-   * Compute the standard deviation of a list of values, defined as the
-   * square root of the variance: std(A) = sqrt(var(A)).
+   * Compute the standard deviation of a matrix or a  list with values.
+   * The standard deviations is defined as the square root of the variance:
+   * `std(A) = sqrt(var(A))`.
    * In case of a (multi dimensional) array or matrix, the standard deviation
    * over all elements will be calculated.
    *
-   *     std(a, b, c, ...)
-   *     std(A)
-   *     std(A, normalization)
+   * Optionally, the type of normalization can be specified as second
+   * parameter. The parameter `normalization` can be one of the following values:
    *
-   * Where `normalization` is a string having one of the following values:
+   * - 'unbiased' (default) The sum of squared errors is divided by (n - 1)
+   * - 'uncorrected'        The sum of squared errors is divided by n
+   * - 'biased'             The sum of squared errors is divided by (n + 1)
    *
-   * @param {Array | Matrix} array                 A single matrix or or multiple scalar values
+   * Syntax:
+   *
+   *     math.std(a, b, c, ...)
+   *     math.std(A)
+   *     math.std(A, normalization)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.std(2, 4, 6);                     // returns 2
+   *     math.std([2, 4, 6, 8]);                // returns 2.581988897471611
+   *     math.std([2, 4, 6, 8], 'uncorrected'); // returns 2.23606797749979
+   *     math.std([2, 4, 6, 8], 'biased');      // returns 2
+   *
+   *     math.std([[1, 2, 3], [4, 5, 6]]);      // returns 1.8708286933869707
+   *
+   * See also:
+   *
+   *    mean, median, max, min, prod, sum, var
+   *
+   * @param {Array | Matrix} array
+   *                        A single matrix or or multiple scalar values
    * @param {String} [normalization='unbiased']
-   *                        Determines how to normalize the standard deviation:
-   *                        - 'unbiased' (default) The sum of squared errors is divided by (n - 1)
-   *                        - 'uncorrected'        The sum of squared errors is divided by n
-   *                        - 'biased'             The sum of squared errors is divided by (n + 1)
-   * @return {*} res
+   *                        Determines how to normalize the variance.
+   *                        Choose 'unbiased' (default), 'uncorrected', or 'biased'.
+   * @return {*} The standard deviation
    */
   math.std = function std(array, normalization) {
     if (arguments.length == 0) {

lib/function/statistics/sum.js

@@ -5,15 +5,29 @@ module.exports = function (math) {
       isCollection = collection.isCollection;
 
   /**
-   * Compute the sum of a list of values
+   * Compute the sum of a matrix or a list with values.
    * In case of a (multi dimensional) array or matrix, the sum of all
    * elements will be calculated.
    *
-   *     sum(a, b, c, ...)
-   *     sum(A)
+   * Syntax:
+   *
+   *     math.sum(a, b, c, ...)
+   *     math.sum(A)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.sum(2, 1, 4, 3);               // returns 10
+   *     math.sum([2, 1, 4, 3]);             // returns 10
+   *     math.sum([[2, 5], [4, 3], [1, 7]]); // returns 22
+   *
+   * See also:
+   *
+   *    mean, median, min, max, prod, std, var
    *
    * @param {... *} args  A single matrix or or multiple scalar values
-   * @return {*} res
+   * @return {*} The sum of all values
    */
   math.sum = function sum(args) {
     if (arguments.length == 0) {

lib/function/statistics/var.js

@@ -9,23 +9,48 @@ module.exports = function (math) {
       DEFAULT_NORMALIZATION = 'unbiased';
 
   /**
-   * Compute the variance of a list of values
+   * Compute the variance of a matrix or a  list with values.
    * In case of a (multi dimensional) array or matrix, the variance over all
    * elements will be calculated.
    *
-   *     var(a, b, c, ...)
-   *     var(A)
-   *     var(A, normalization)
+   * Optionally, the type of normalization can be specified as second
+   * parameter. The parameter `normalization` can be one of the following values:
    *
-   * Where `normalization` is a string having one of the following values:
+   * - 'unbiased' (default) The sum of squared errors is divided by (n - 1)
+   * - 'uncorrected'        The sum of squared errors is divided by n
+   * - 'biased'             The sum of squared errors is divided by (n + 1)
+
+   * Note that older browser may not like the variable name `var`. In that
+   * case, the function can be called as `math['var'](...)` instead of
+   * `math.var(...)`.
    *
-   * @param {Array | Matrix} array                 A single matrix or or multiple scalar values
+   * Syntax:
+   *
+   *     math.var(a, b, c, ...)
+   *     math.var(A)
+   *     math.var(A, normalization)
+   *
+   * Examples:
+   *
+   *     var math = mathjs();
+   *
+   *     math.var(2, 4, 6);                     // returns 4
+   *     math.var([2, 4, 6, 8]);                // returns 6.666666666666667
+   *     math.var([2, 4, 6, 8], 'uncorrected'); // returns 5
+   *     math.var([2, 4, 6, 8], 'biased');      // returns 4
+   *
+   *     math.var([[1, 2, 3], [4, 5, 6]]);      // returns 3.5
+   *
+   * See also:
+   *
+   *    mean, median, max, min, prod, std, sum
+   *
+   * @param {Array | Matrix} array
+   *                        A single matrix or or multiple scalar values
    * @param {String} [normalization='unbiased']
-   *                        Determines how to normalize the variance:
-   *                        - 'unbiased' (default) The sum of squared errors is divided by (n - 1)
-   *                        - 'uncorrected'        The sum of squared errors is divided by n
-   *                        - 'biased'             The sum of squared errors is divided by (n + 1)
-   * @return {*} res
+   *                        Determines how to normalize the variance.
+   *                        Choose 'unbiased' (default), 'uncorrected', or 'biased'.
+   * @return {*} The variance
    */
   math['var'] = function variance(array, normalization) {
     if (arguments.length == 0) {