From 830367a49431c2a12c2f2dfc3beb71dcb4ec5b53 Mon Sep 17 00:00:00 2001
From: jos <wjosdejong@gmail.com>
Date: Sun, 18 May 2014 22:21:00 +0200
Subject: [PATCH] More docs added

---
 docs/reference/functions/combinations.md      |  3 +-
 docs/reference/functions/concat.md            | 36 ++++++++++---
 docs/reference/functions/det.md               | 29 +++++++++-
 docs/reference/functions/eye.md               | 35 +++++++++---
 docs/reference/functions/inv.md               | 25 +++++++--
 docs/reference/functions/max.md               | 44 ++++++++++++---
 docs/reference/functions/mean.md              | 40 +++++++++++---
 docs/reference/functions/median.md            | 35 +++++++++---
 docs/reference/functions/min.md               | 48 +++++++++++++----
 docs/reference/functions/multiply.md          |  2 +-
 docs/reference/functions/ones.md              | 36 ++++++++++---
 docs/reference/functions/parse.md             |  5 +-
 docs/reference/functions/prod.md              | 36 +++++++++++--
 docs/reference/functions/range.md             | 54 ++++++++++---------
 docs/reference/functions/size.md              | 26 +++++++--
 docs/reference/functions/squeeze.md           | 32 +++++++++--
 docs/reference/functions/std.md               | 51 ++++++++++++++----
 docs/reference/functions/sum.md               | 32 +++++++++--
 docs/reference/functions/transpose.md         | 29 ++++++++--
 docs/reference/functions/var.md               | 51 +++++++++++++++---
 docs/reference/functions/zeros.md             | 36 ++++++++++---
 lib/expression/docs/function/matrix/concat.js | 16 +++---
 .../docs/function/statistics/median.js        |  2 +-
 lib/function/matrix/concat.js                 | 30 ++++++++---
 lib/function/matrix/det.js                    | 28 ++++++++--
 lib/function/matrix/eye.js                    | 27 +++++++---
 lib/function/matrix/inv.js                    | 23 +++++---
 lib/function/matrix/ones.js                   | 29 +++++++---
 lib/function/matrix/range.js                  | 41 ++++++++------
 lib/function/matrix/size.js                   | 21 ++++++--
 lib/function/matrix/squeeze.js                | 28 ++++++++--
 lib/function/matrix/transpose.js              | 23 ++++++--
 lib/function/matrix/zeros.js                  | 29 +++++++---
 lib/function/probability/combinations.js      |  6 +--
 lib/function/statistics/max.js                | 34 +++++++++---
 lib/function/statistics/mean.js               | 30 ++++++++---
 lib/function/statistics/median.js             | 25 ++++++---
 lib/function/statistics/min.js                | 38 +++++++++----
 lib/function/statistics/prod.js               | 26 +++++++--
 lib/function/statistics/std.js                | 48 ++++++++++++-----
 lib/function/statistics/sum.js                | 22 ++++++--
 lib/function/statistics/var.js                | 47 ++++++++++++----
 42 files changed, 987 insertions(+), 271 deletions(-)

diff --git a/docs/reference/functions/combinations.md b/docs/reference/functions/combinations.md
index e98adca06..b85c9be1e 100644
--- a/docs/reference/functions/combinations.md
+++ b/docs/reference/functions/combinations.md
@@ -17,7 +17,8 @@ math.combinations(n, k)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-
+`n` | Number &#124; BigNumber | Total number of objects in the set
+`k` | Number &#124; BigNumber | Number of objects in the subset
 
 ### Returns
 
diff --git a/docs/reference/functions/concat.md b/docs/reference/functions/concat.md
index e06039ea8..817c39a57 100644
--- a/docs/reference/functions/concat.md
+++ b/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 &#124; Matrix | 
+`args` | ... Array &#124; Matrix | Two or more matrices
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array &#124; Matrix | res
+Array &#124; 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. -->
diff --git a/docs/reference/functions/det.md b/docs/reference/functions/det.md
index 1e50f2391..b4fa21240 100644
--- a/docs/reference/functions/det.md
+++ b/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 &#124; Matrix | 
+`x` | Array &#124; 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. -->
diff --git a/docs/reference/functions/eye.md b/docs/reference/functions/eye.md
index e022f0023..5294e832d 100644
--- a/docs/reference/functions/eye.md
+++ b/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 &#124; Matrix &#124; Array | 
+`size` | ...Number &#124; Matrix &#124; Array | The size for the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix &#124; Array &#124; Number | matrix
+Matrix &#124; Array &#124; 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. -->
diff --git a/docs/reference/functions/inv.md b/docs/reference/functions/inv.md
index 5a2d9046f..84158a55c 100644
--- a/docs/reference/functions/inv.md
+++ b/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 &#124; Complex &#124; Array &#124; Matrix | 
+`x` | Number &#124; Complex &#124; Array &#124; Matrix | Matrix to be inversed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Number &#124; Complex &#124; Array &#124; Matrix | inv
+Number &#124; Complex &#124; Array &#124; 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. -->
diff --git a/docs/reference/functions/max.md b/docs/reference/functions/max.md
index 529ebc5d2..3f457d8c7 100644
--- a/docs/reference/functions/max.md
+++ b/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. -->
diff --git a/docs/reference/functions/mean.md b/docs/reference/functions/mean.md
index d471989c9..bfbb7137d 100644
--- a/docs/reference/functions/mean.md
+++ b/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. -->
diff --git a/docs/reference/functions/median.md b/docs/reference/functions/median.md
index 83e2bfc29..580cec75c 100644
--- a/docs/reference/functions/median.md
+++ b/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. -->
diff --git a/docs/reference/functions/min.md b/docs/reference/functions/min.md
index d23cee305..4a6877f1a 100644
--- a/docs/reference/functions/min.md
+++ b/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. -->
diff --git a/docs/reference/functions/multiply.md b/docs/reference/functions/multiply.md
index 15dd35e85..7a44a4149 100644
--- a/docs/reference/functions/multiply.md
+++ b/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.
 
 
diff --git a/docs/reference/functions/ones.md b/docs/reference/functions/ones.md
index f973d28c2..3ebf826e2 100644
--- a/docs/reference/functions/ones.md
+++ b/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 &#124; Array | 
+`size` | ...Number &#124; Array | The size of each dimension of the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array &#124; Matrix &#124; Number | matrix
+Array &#124; Matrix &#124; 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. -->
diff --git a/docs/reference/functions/parse.md b/docs/reference/functions/parse.md
index dd1760280..bcccd4407 100644
--- a/docs/reference/functions/parse.md
+++ b/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]
 ```
 
 
diff --git a/docs/reference/functions/prod.md b/docs/reference/functions/prod.md
index e08510f2e..d3182fa53 100644
--- a/docs/reference/functions/prod.md
+++ b/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. -->
diff --git a/docs/reference/functions/range.md b/docs/reference/functions/range.md
index 59659f29f..ba7252312 100644
--- a/docs/reference/functions/range.md
+++ b/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 &#124; 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. -->
diff --git a/docs/reference/functions/size.md b/docs/reference/functions/size.md
index d7a77d4db..f1506124e 100644
--- a/docs/reference/functions/size.md
+++ b/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 &#124; Number &#124; Complex &#124; Unit &#124; String &#124; Array &#124; Matrix | 
+`x` | Boolean &#124; Number &#124; Complex &#124; Unit &#124; String &#124; Array &#124; Matrix | A matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array &#124; Matrix | res
+Array &#124; 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]
+```
 
 
 
diff --git a/docs/reference/functions/squeeze.md b/docs/reference/functions/squeeze.md
index 1e8998e5d..4a26a8265 100644
--- a/docs/reference/functions/squeeze.md
+++ b/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 &#124; Array | 
+`x` | Matrix &#124; Array | Matrix to be squeezed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix &#124; Array | res
+Matrix &#124; 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. -->
diff --git a/docs/reference/functions/std.md b/docs/reference/functions/std.md
index 7ff02d787..4d9d81e93 100644
--- a/docs/reference/functions/std.md
+++ b/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 &#124; 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 &#124; 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. -->
diff --git a/docs/reference/functions/sum.md b/docs/reference/functions/sum.md
index 93c506ca9..983cc3b13 100644
--- a/docs/reference/functions/sum.md
+++ b/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. -->
diff --git a/docs/reference/functions/transpose.md b/docs/reference/functions/transpose.md
index 2ea5381f7..ca068b835 100644
--- a/docs/reference/functions/transpose.md
+++ b/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 &#124; Matrix | 
+`x` | Array &#124; Matrix | Matrix to be transposed
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array &#124; Matrix | transpose
+Array &#124; 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. -->
diff --git a/docs/reference/functions/var.md b/docs/reference/functions/var.md
index c157bb8aa..de0ab3822 100644
--- a/docs/reference/functions/var.md
+++ b/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 &#124; 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 &#124; 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. -->
diff --git a/docs/reference/functions/zeros.md b/docs/reference/functions/zeros.md
index 8eb59dc54..ca146cf94 100644
--- a/docs/reference/functions/zeros.md
+++ b/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 &#124; Array | 
+`size` | ...Number &#124; Array | The size of each dimension of the matrix
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Array &#124; Matrix &#124; Number | matrix
+Array &#124; Matrix &#124; 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. -->
diff --git a/lib/expression/docs/function/matrix/concat.js b/lib/expression/docs/function/matrix/concat.js
index 52ff9b2fb..c42b7b390 100644
--- a/lib/expression/docs/function/matrix/concat.js
+++ b/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'
diff --git a/lib/expression/docs/function/statistics/median.js b/lib/expression/docs/function/statistics/median.js
index eaff2a832..920dbf21b 100644
--- a/lib/expression/docs/function/statistics/median.js
+++ b/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': [
diff --git a/lib/function/matrix/concat.js b/lib/function/matrix/concat.js
index 0a468a336..7e8571801 100644
--- a/lib/function/matrix/concat.js
+++ b/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,
diff --git a/lib/function/matrix/det.js b/lib/function/matrix/det.js
index ac37695d8..94ce8fa9e 100644
--- a/lib/function/matrix/det.js
+++ b/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) {
diff --git a/lib/function/matrix/eye.js b/lib/function/matrix/eye.js
index 58e53b4ac..bc03fd0f3 100644
--- a/lib/function/matrix/eye.js
+++ b/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),
diff --git a/lib/function/matrix/inv.js b/lib/function/matrix/inv.js
index af417e7b4..c0478d947 100644
--- a/lib/function/matrix/inv.js
+++ b/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) {
diff --git a/lib/function/matrix/ones.js b/lib/function/matrix/ones.js
index 0c603ffc7..264b18c6b 100644
--- a/lib/function/matrix/ones.js
+++ b/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);
diff --git a/lib/function/matrix/range.js b/lib/function/matrix/range.js
index 35b7cfade..612c0a3fa 100644
--- a/lib/function/matrix/range.js
+++ b/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) {
diff --git a/lib/function/matrix/size.js b/lib/function/matrix/size.js
index 01ff54f6f..70272d827 100644
--- a/lib/function/matrix/size.js
+++ b/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) {
diff --git a/lib/function/matrix/squeeze.js b/lib/function/matrix/squeeze.js
index 6b092f447..ec83e51d9 100644
--- a/lib/function/matrix/squeeze.js
+++ b/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) {
diff --git a/lib/function/matrix/transpose.js b/lib/function/matrix/transpose.js
index 4183201bd..67fdaded5 100644
--- a/lib/function/matrix/transpose.js
+++ b/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) {
diff --git a/lib/function/matrix/zeros.js b/lib/function/matrix/zeros.js
index 7c39582fd..378e5065d 100644
--- a/lib/function/matrix/zeros.js
+++ b/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);
diff --git a/lib/function/probability/combinations.js b/lib/function/probability/combinations.js
index d28da47a4..0373bbd1e 100644
--- a/lib/function/probability/combinations.js
+++ b/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;
diff --git a/lib/function/statistics/max.js b/lib/function/statistics/max.js
index 67f6d4a13..e2e334bc6 100644
--- a/lib/function/statistics/max.js
+++ b/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) {
diff --git a/lib/function/statistics/mean.js b/lib/function/statistics/mean.js
index 8ff434ed1..afb7c9bbd 100644
--- a/lib/function/statistics/mean.js
+++ b/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) {
diff --git a/lib/function/statistics/median.js b/lib/function/statistics/median.js
index 6e7ce8af3..5503e9d64 100644
--- a/lib/function/statistics/median.js
+++ b/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) {
diff --git a/lib/function/statistics/min.js b/lib/function/statistics/min.js
index 8ad199be5..43b1e7e60 100644
--- a/lib/function/statistics/min.js
+++ b/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) {
diff --git a/lib/function/statistics/prod.js b/lib/function/statistics/prod.js
index 48db0db7d..84fa10f2a 100644
--- a/lib/function/statistics/prod.js
+++ b/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) {
diff --git a/lib/function/statistics/std.js b/lib/function/statistics/std.js
index 0811439ec..0b77dc3e5 100644
--- a/lib/function/statistics/std.js
+++ b/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) {
diff --git a/lib/function/statistics/sum.js b/lib/function/statistics/sum.js
index b8715906d..c619d012b 100644
--- a/lib/function/statistics/sum.js
+++ b/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) {
diff --git a/lib/function/statistics/var.js b/lib/function/statistics/var.js
index e04289ff7..b4a2b46b1 100644
--- a/lib/function/statistics/var.js
+++ b/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) {