More docs added

docs/reference/functions/clone.md

@@ -1,21 +1,38 @@
 # Function clone
 
-Clone an object
+Clone an object.
 
-    clone(x)
 
+## Syntax
+
+```js
+math.clone(x)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | * | 
+`x` | * | Object to be cloned
 
 ### Returns
 
 Type | Description
 ---- | -----------
-* | clone
+* | A clone of object x
+
+
+## Examples
+
+```js
+var math = mathjs();
+
+math.clone(3.5);              // returns number 3.5
+math.clone(2 - 4i);           // returns Complex 2 - 4i
+math.clone(45 deg);           // returns Unit 45 deg
+math.clone([[1, 2], [3, 4]]); // returns Array [[1, 2], [3, 4]]
+math.clone("hello world");    // returns string "hello world"
+```
 
 
 

docs/reference/functions/combinations.md

@@ -1,11 +1,15 @@
 # Function combinations
 
-Compute the number of combinations of n items taken k at a time
+Compute the number of ways of picking `k` unordered outcomes from `n` possibilities.
 
-    combinations(n, k)
+Combinations only takes integer arguments. The following condition must be enforced: k <= n.
 
-combinations only takes integer arguments the following condition must be enforced: k <= n
 
+## Syntax
+
+```js
+math.combinations(n, k)
+```
 
 ### Parameters
 
@@ -17,9 +21,22 @@ Parameter | Type | Description
 
 Type | Description
 ---- | -----------
-Number &#124; BigNumber | combinations
+Number &#124; BigNumber | Number of possible combinations.
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.combinations(7, 5); // returns 21
+```
+
+
+## See also
+
+[permutations](permutations.md),
+[factorial](factorial.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/factorial.md

@@ -2,24 +2,42 @@
 
 Compute the factorial of a value
 
-    n!     factorial(n)
-
 Factorial only supports an integer value as argument. For matrices, the function is evaluated element wise.
 
 
+## Syntax
+
+```js
+math.factorial(n)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-
+`n` | Number | BigNumber | Array | Matrix | An integer number
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Number | BigNumber | Array | Matrix | res
+Number | BigNumber | Array | Matrix | The factorial of `n`
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.factorial(5);    // returns 120
+math.factorial(3);    // returns 6
+```
+
+
+## See also
+
+[combinations](combinations.md),
+[permutations](permutations.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/forEach.md

@@ -1,14 +1,20 @@
 # Function forEach
 
-Execute a callback method on each entry of the matrix or the array.
+Iterate over all elements of a matrix/array, and executes the given callback function.
 
 
+## Syntax
+
+```js
+math.forEach(x, callback)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Matrix/array | The container to iterate on.
-`callback` | function | The callback method is invoked with three parameters: the value of the element, the index of the element, and the Matrix/array being traversed.
+`x` | Matrix | Array | The matrix to iterate on.
+`callback` | Function | The callback function is invoked with three parameters: the value of the element, the index of the element, and the Matrix/array being traversed.
 
 ### Returns
 
@@ -17,6 +23,18 @@ Type | Description
  | undefined
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.forEach([1, 2, 3], function(value) {
+console.log(value);
+});
+// outputs 1, 2, 3
+```
+
+
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/format.md

@@ -6,10 +6,10 @@ Format a value of any type into a string.
 ## Syntax
 
 ```js
-format(value)
-format(value, options)
-format(value, precision)
-format(value, fn)
+math.format(value)
+math.format(value, options)
+math.format(value, precision)
+math.format(value, fn)
 ```
 
 ### Parameters
@@ -17,7 +17,7 @@ format(value, fn)
 Parameter | Type | Description
 --------- | ---- | -----------
 `value` | * | Value to be stringified
-`options` | Object | Function | Number | 
+`options` | Object | Function | Number | Formatting options
 
 ### Returns
 
@@ -29,17 +29,20 @@ String | str The formatted value
 ## Examples
 
 ```js
-format(6.4);                                        // '6.4'
-format(1240000);                                    // '1.24e6'
-format(1/3);                                        // '0.3333333333333333'
-format(1/3, 3);                                     // '0.333'
-format(21385, 2);                                   // '21000'
-format(12.071, {notation: 'fixed'});                // '12'
-format(2.3,    {notation: 'fixed', precision: 2});  // '2.30'
-format(52.8,   {notation: 'exponential'});          // '5.28e+1'
+math.format(6.4);                                        // returns '6.4'
+math.format(1240000);                                    // returns '1.24e6'
+math.format(1/3);                                        // returns '0.3333333333333333'
+math.format(1/3, 3);                                     // returns '0.333'
+math.format(21385, 2);                                   // returns '21000'
+math.format(12.071, {notation: 'fixed'});                // returns '12'
+math.format(2.3,    {notation: 'fixed', precision: 2});  // returns '2.30'
+math.format(52.8,   {notation: 'exponential'});          // returns '5.28e+1'
 ```
 
 
+## See also
+
+[print](print.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/ifElse.md

@@ -5,6 +5,12 @@ Execute a conditional expression.
 In case of a matrix or array, the test is done element wise, the true and false part can be either a matrix/array with the same size of the condition, or a scalar value.
 
 
+## Syntax
+
+```js
+math.ifElse(condition, trueExpr, falseExpr
+```
+
 ### Parameters
 
 Parameter | Type | Description
@@ -20,6 +26,16 @@ Type | Description
 * | The evaluated return expression
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.ifElse(true, 'yes', 'no');           // returns 'yes'
+math.ifElse([4, 6, 0, -1], true, false);  // returns [true, true, false, true]
+```
+
+
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/import.md

@@ -3,12 +3,18 @@
 Import functions from an object or a module
 
 
+## Syntax
+
+```js
+math.import(x)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`object` | String | Object | 
-`options` | Object | Available options: {Boolean} override If true, existing functions will be overwritten. False by default. {Boolean} wrap If true (default), the functions will be wrapped in a wrapper function which converts data types like Matrix to primitive data types like Array. The wrapper is needed when extending math.js with libraries which do not support the math.js data types.
+`object` | String | Object | Object with functions to be imported.
+`options` | Object | Available options: {Boolean} override If true, existing functions will be overwritten. False by default. {Boolean} wrap If true (default), the functions will be wrapped in a wrapper function which converts data types like Matrix to primitive data types like Array. The wrapper is needed when extending math.js with libraries which do not
 
 ### Returns
 
@@ -17,6 +23,31 @@ Type | Description
  | undefined
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+// define new functions and variables
+math.import({
+myvalue: 42,
+hello: function (name) {
+return 'hello, ' + name + '!';
+}
+});
+
+// use the imported function and variable
+math.myvalue * 2;               // 84
+math.hello('user');             // 'hello, user!'
+
+// import the npm module numbers
+// (must be installed first with `npm install numbers`)
+math.import('numbers');
+
+math.fibonacci(7); // returns 13
+```
+
+
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/map.md

@@ -3,18 +3,35 @@
 Create a new matrix or array with the results of the callback function executed on each entry of the matrix/array.
 
 
+## Syntax
+
+```js
+math.map(x, callback)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Matrix/array | The container to iterate on.
-`callback` | function | The callback method is invoked with three parameters: the value of the element, the index of the element, and the Matrix being traversed.
+`x` | Matrix | Array | The matrix to iterate on.
+`callback` | Function | The callback method is invoked with three parameters: the value of the element, the index of the element, and the matrix being traversed.
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Matrix/array | container
+Matrix | array | Transformed map of x
+
+
+## Examples
+
+```js
+var math = mathjs();
+
+math.map([1, 2, 3], function(value) {
+return value * value;
+});  // returns [1, 4, 9]
+```
 
 
 

docs/reference/functions/permutations.md

@@ -1,25 +1,45 @@
 # Function permutations
 
-Compute the number of permutations of n items taken k at a time
+Compute the number of ways of obtaining an ordered subset of `k` elements from a set of `n` elements.
 
-    permutations(n)     permutations(n, k)
+Permutations only takes integer arguments. The following condition must be enforced: k <= n.
 
-permutations only takes integer arguments the following condition must be enforced: k <= n
 
+## Syntax
+
+```js
+math.permutations(n)
+math.permutations(n, k)
+```
 
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-
+`n` | Number &#124; BigNumber | The number of objects in total
+`k` | Number &#124; BigNumber | The number of objects in the subset
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Number &#124; BigNumber | permutations
+Number &#124; BigNumber | The number of permutations
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.permutations(5);     // 120
+math.permutations(5, 3);  // 60
+```
+
+
+## See also
+
+[combinations](combinations.md),
+[factorial](factorial.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/print.md

@@ -14,33 +14,41 @@ math.print(template, values, precision)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`template` | String | 
-`values` | Object | 
+`template` | String | A string containing variable placeholders.
+`values` | Object | An object containing variables which will be filled in in the template.
 `precision` | Number | Number of digits to format numbers. If not provided, the value will not be rounded.
 
 ### Returns
 
 Type | Description
 ---- | -----------
-String | str
+String | Interpolated string
 
 
 ## Examples
 
 ```js
+var math = mathjs();
+
+// the following outputs: 'Lucy is 5 years old'
+math.print('Lucy is $age years old', {age: 5});
+
 // the following outputs: 'The value of pi is 3.141592654'
-math.format('The value of pi is $pi', {pi: math.pi}, 10);
+math.print('The value of pi is $pi', {pi: math.pi}, 10);
 
 // the following outputs: 'hello Mary! The date is 2013-03-23'
-math.format('Hello $user.name! The date is $date', {
+math.print('Hello $user.name! The date is $date', {
 user: {
 name: 'Mary',
 },
-date: new Date().toISOString().substring(0, 10)
+date: new Date(2013, 2, 23).toISOString().substring(0, 10)
 });
 ```
 
 
+## See also
+
+[format](format.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/to.md

@@ -2,25 +2,43 @@
 
 Change the unit of a value.
 
-    x to unit     to(x, unit)
-
 For matrices, the function is evaluated element wise.
 
 
+## Syntax
+
+```js
+math.to(x, unit)
+```
+
 ### Parameters
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | Unit | Array | Matrix | 
-`unit` | Unit | Array | Matrix | 
+`x` | Unit | Array | Matrix | The unit to be converted.
+`unit` | Unit | Array | Matrix | New unit. Can be a string like "cm" or a unit without value.
 
 ### Returns
 
 Type | Description
 ---- | -----------
-Unit | Array | Matrix | res
+Unit | Array | Matrix | value with changed, fixed unit.
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.to(math.unit('2 inch'), 'cm');                   // returns Unit 5.08 cm
+math.to(math.unit('2 inch'), math.unit(null, 'cm'));  // returns Unit 5.08 cm
+math.to(math.unit(16, 'bytes'), 'bits');              // returns Unit 128 bits
+```
+
+
+## See also
+
+[unit](unit.md)
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

docs/reference/functions/typeof.md

@@ -1,6 +1,6 @@
 # Function typeof
 
-Determines the type of a variable.
+Determine the type of a variable.
 
 
 ## Syntax
@@ -13,7 +13,7 @@ math.typeof(x)
 
 Parameter | Type | Description
 --------- | ---- | -----------
-`x` | * | 
+`x` | * | The variable for which to test the type.
 
 ### Returns
 
@@ -22,6 +22,18 @@ Type | Description
 String | Lower case type, for example 'number', 'string', 'array'.
 
 
+## Examples
+
+```js
+var math = mathjs();
+
+math.typeof(3.5);             // returns 'number'
+math.typeof(2 - 4i);          // returns 'complex'
+math.typeof(45 deg);          // returns 'unit'
+math.typeof("hello world");   // returns 'string'
+```
+
+
 
 
 <!-- Note: This file is automatically generated from source code comments. Changes made in this file will be overridden. -->

lib/expression/docs/function/probability/factorial.js

@@ -11,5 +11,5 @@ module.exports = {
     '5*4*3*2*1',
     '3!'
   ],
-  'seealso': []
+  'seealso': ['combinations', 'permutations']
 };

lib/expression/docs/function/probability/permutations.js

@@ -8,7 +8,7 @@ module.exports = {
   'description': 'Compute the number of permutations of n items taken k at a time',
   'examples': [
     'permutations(5)',
-    'permutations(5, 4)'
+    'permutations(5, 3)'
   ],
   'seealso': ['combinations', 'factorial']
 };

lib/expression/docs/function/units/to.js

@@ -7,8 +7,8 @@ module.exports = {
   ],
   'description': 'Change the unit of a value.',
   'examples': [
-    '5 inch in cm',
-    '3.2kg in g',
+    '5 inch to cm',
+    '3.2kg to g',
     '16 bytes in bits'
   ],
   'seealso': []

lib/expression/docs/function/utils/forEach.js

@@ -4,9 +4,9 @@ module.exports = {
   'syntax': [
     'forEach(x, callback)'
   ],
-  'description': 'Iterates over all elements of a matrix/array, and executes the given callback.',
+  'description': 'Iterates over all elements of a matrix/array, and executes the given callback function.',
   'examples': [
     'forEach([1, 2, 3], function(val) { console.log(val) })'
   ],
-  'seealso': []
+  'seealso': ['unit']
 };

lib/expression/docs/function/utils/ifElse.js

@@ -6,7 +6,7 @@ module.exports = {
   ],
   'description': 'Executes a conditional expression.',
   'examples': [
-    'ifElse(10 > 0, 10, 0)',
+    'ifElse(10 > 0, 1, 0)',
     'ifElse("", true, false)',
     'ifElse([4, 6, 0, -1], true, false)'
   ],

lib/expression/docs/function/utils/map.js

@@ -6,7 +6,7 @@ module.exports = {
   ],
   'description': 'Create a new matrix or array with the results of the callback function executed on each entry of the matrix/array.',
   'examples': [
-    'map([1, 2, 3], function(val) { return math.max(val, 1.5) })'
+    'map([1, 2, 3], function(val) { return value * value })'
   ],
   'seealso': []
 };

lib/function/probability/combinations.js

@@ -8,16 +8,29 @@ module.exports = function (math) {
       isInteger = util.number.isInteger;
 
   /**
-   * Compute the number of combinations of n items taken k at a time
+   * Compute the number of ways of picking `k` unordered outcomes from `n`
+   * possibilities.
    *
-   *     combinations(n, k)
+   * Combinations only takes integer arguments.
+   * The following condition must be enforced: k <= n.
    *
-   * combinations only takes integer arguments
-   * the following condition must be enforced: k <= n
+   * Syntax:
    *
-   * @Param {Number | BigNumber} n
-   * @Param {Number | BigNumber} k
-   * @return {Number | BigNumber} combinations
+   *     math.combinations(n, k)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.combinations(7, 5); // returns 21
+   *
+   * See also:
+   *
+   *    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.
    */
   math.combinations = function combinations (n, k) {
     var max, result, i,ii;

lib/function/probability/factorial.js

@@ -12,14 +12,26 @@ module.exports = function (math) {
   /**
    * Compute the factorial of a value
    *
-   *     n!
-   *     factorial(n)
-   *
    * Factorial only supports an integer value as argument.
    * For matrices, the function is evaluated element wise.
    *
-   * @Param {Number | BigNumber | Array | Matrix} n
-   * @return {Number | BigNumber | Array | Matrix} res
+   * Syntax:
+   *
+   *    math.factorial(n)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.factorial(5);    // returns 120
+   *    math.factorial(3);    // returns 6
+   *
+   * See also:
+   *
+   *    combinations, permutations
+   *
+   * @param {Number | BigNumber | Array | Matrix} n   An integer number
+   * @return {Number | BigNumber | Array | Matrix}    The factorial of `n`
    */
   math.factorial = function factorial (n) {
     var value, res;

lib/function/probability/permutations.js

@@ -7,17 +7,31 @@ module.exports = function (math) {
       isInteger = util.number.isInteger;
 
   /**
-   * Compute the number of permutations of n items taken k at a time
+   * Compute the number of ways of obtaining an ordered subset of `k` elements
+   * from a set of `n` elements.
    *
-   *     permutations(n)
-   *     permutations(n, k)
+   * Permutations only takes integer arguments.
+   * The following condition must be enforced: k <= n.
    *
-   * permutations only takes integer arguments
-   * the following condition must be enforced: k <= n
+   * Syntax:
    *
-   * @Param {Number | BigNumber} n
-   * @Param {Number | BigNumber} k
-   * @return {Number | BigNumber} permutations
+   *     math.permutations(n)
+   *     math.permutations(n, k)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.permutations(5);     // 120
+   *    math.permutations(5, 3);  // 60
+   *
+   * See also:
+   *
+   *    combinations, factorial
+   *
+   * @param {Number | BigNumber} n  The number of objects in total
+   * @param {Number | BigNumber} k  The number of objects in the subset
+   * @return {Number | BigNumber}   The number of permutations
    */
   math.permutations = function permutations (n, k) {
     var result, i;

lib/function/units/to.js

@@ -11,14 +11,28 @@ module.exports = function (math) {
   /**
    * Change the unit of a value.
    *
-   *     x to unit
-   *     to(x, unit)
-   *
    * For matrices, the function is evaluated element wise.
    *
-   * @param {Unit | Array | Matrix} x
-   * @param {Unit | Array | Matrix} unit
-   * @return {Unit | Array | Matrix} res
+   * Syntax:
+   *
+   *    math.to(x, unit)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.to(math.unit('2 inch'), 'cm');                   // returns Unit 5.08 cm
+   *    math.to(math.unit('2 inch'), math.unit(null, 'cm'));  // returns Unit 5.08 cm
+   *    math.to(math.unit(16, 'bytes'), 'bits');              // returns Unit 128 bits
+   *
+   * See also:
+   *
+   *    unit
+   *
+   * @param {Unit | Array | Matrix} x     The unit to be converted.
+   * @param {Unit | Array | Matrix} unit  New unit. Can be a string like "cm"
+   *                                      or a unit without value.
+   * @return {Unit | Array | Matrix} value with changed, fixed unit.
    */
   math.to = function to(x, unit) {
     if (arguments.length != 2) {

lib/function/utils/clone.js

@@ -3,12 +3,24 @@ module.exports = function (math) {
       object = util.object;
 
   /**
-   * Clone an object
+   * Clone an object.
    *
-   *     clone(x)
+   * Syntax:
    *
-   * @param {*} x
-   * @return {*} clone
+   *     math.clone(x)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.clone(3.5);              // returns number 3.5
+   *    math.clone(2 - 4i);           // returns Complex 2 - 4i
+   *    math.clone(45 deg);           // returns Unit 45 deg
+   *    math.clone([[1, 2], [3, 4]]); // returns Array [[1, 2], [3, 4]]
+   *    math.clone("hello world");    // returns string "hello world"
+   *
+   * @param {*} x   Object to be cloned
+   * @return {*} A clone of object x
    */
   math.clone = function clone (x) {
     if (arguments.length != 1) {

lib/function/utils/forEach.js

@@ -2,9 +2,23 @@ module.exports = function (math) {
   var isMatrix = require('../../type/Matrix').isMatrix;
 
   /**
-   * Execute a callback method on each entry of the matrix or the array.
-   * @param {Matrix/array} x      The container to iterate on.
-   * @param {function} callback   The callback method is invoked with three
+   * Iterate over all elements of a matrix/array, and executes the given callback function.
+   *
+   * Syntax:
+   *
+   *    math.forEach(x, callback)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.forEach([1, 2, 3], function(value) {
+   *      console.log(value);
+   *    });
+   *    // outputs 1, 2, 3
+   *
+   * @param {Matrix | Array} x    The matrix to iterate on.
+   * @param {Function} callback   The callback function is invoked with three
    *                              parameters: the value of the element, the index
    *                              of the element, and the Matrix/array being traversed.
    */
@@ -36,6 +50,6 @@ module.exports = function (math) {
       }
     };
     recurse(array, 0);
-  };
+  }
 
 };

lib/function/utils/format.js

@@ -7,10 +7,10 @@ module.exports = function (math) {
    *
    * Syntax:
    *
-   *    format(value)
-   *    format(value, options)
-   *    format(value, precision)
-   *    format(value, fn)
+   *    math.format(value)
+   *    math.format(value, options)
+   *    math.format(value, precision)
+   *    math.format(value, fn)
    *
    * Where:
    *
@@ -53,17 +53,21 @@ module.exports = function (math) {
    *
    * Examples:
    *
-   *    format(6.4);                                        // '6.4'
-   *    format(1240000);                                    // '1.24e6'
-   *    format(1/3);                                        // '0.3333333333333333'
-   *    format(1/3, 3);                                     // '0.333'
-   *    format(21385, 2);                                   // '21000'
-   *    format(12.071, {notation: 'fixed'});                // '12'
-   *    format(2.3,    {notation: 'fixed', precision: 2});  // '2.30'
-   *    format(52.8,   {notation: 'exponential'});          // '5.28e+1'
+   *    math.format(6.4);                                        // returns '6.4'
+   *    math.format(1240000);                                    // returns '1.24e6'
+   *    math.format(1/3);                                        // returns '0.3333333333333333'
+   *    math.format(1/3, 3);                                     // returns '0.333'
+   *    math.format(21385, 2);                                   // returns '21000'
+   *    math.format(12.071, {notation: 'fixed'});                // returns '12'
+   *    math.format(2.3,    {notation: 'fixed', precision: 2});  // returns '2.30'
+   *    math.format(52.8,   {notation: 'exponential'});          // returns '5.28e+1'
    *
-   * @param {*} value             Value to be stringified
-   * @param {Object | Function | Number} [options]
+   * See also:
+   *
+   *    print
+   *
+   * @param {*} value                               Value to be stringified
+   * @param {Object | Function | Number} [options]  Formatting options
    * @return {String} str The formatted value
    */
   math.format = function format (value, options) {

lib/function/utils/ifElse.js

@@ -22,6 +22,17 @@ module.exports = function (math) {
    * true and false part can be either a matrix/array with the same size
    * of the condition, or a scalar value.
    *
+   * Syntax:
+   *
+   *    math.ifElse(condition, trueExpr, falseExpr
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.ifElse(true, 'yes', 'no');           // returns 'yes'
+   *    math.ifElse([4, 6, 0, -1], true, false);  // returns [true, true, false, true]
+   *
    * @param {Number | Boolean | String | Complex | BigNumber | Unit | Matrix | Array} condition
    *                        The conditional expression
    * @param {*} trueExpr    The true expression

lib/function/utils/import.js

@@ -11,7 +11,34 @@ module.exports = function (math) {
 
   /**
    * Import functions from an object or a module
-   * @param {String | Object} object
+   *
+   * Syntax:
+   *
+   *    math.import(x)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    // define new functions and variables
+   *    math.import({
+   *      myvalue: 42,
+   *      hello: function (name) {
+   *        return 'hello, ' + name + '!';
+   *      }
+   *    });
+   *
+   *    // use the imported function and variable
+   *    math.myvalue * 2;               // 84
+   *    math.hello('user');             // 'hello, user!'
+   *
+   *    // import the npm module numbers
+   *    // (must be installed first with `npm install numbers`)
+   *    math.import('numbers');
+   *
+   *    math.fibonacci(7); // returns 13
+   *
+   * @param {String | Object} object  Object with functions to be imported.
    * @param {Object} [options]        Available options:
    *                                  {Boolean} override
    *                                      If true, existing functions will be
@@ -23,9 +50,8 @@ module.exports = function (math) {
    *                                      primitive data types like Array.
    *                                      The wrapper is needed when extending
    *                                      math.js with libraries which do not
-   *                                      support the math.js data types.
    */
-// TODO: return status information
+  // TODO: return status information
   math['import'] = function math_import(object, options) {
     var num = arguments.length;
     if (num != 1 && num != 2) {

lib/function/utils/map.js

@@ -1,14 +1,28 @@
 module.exports = function (math) {
   var isMatrix = require('../../type/Matrix').isMatrix;
 
+
   /**
    * Create a new matrix or array with the results of the callback function executed on
    * each entry of the matrix/array.
-   * @param {Matrix/array} x      The container to iterate on.
-   * @param {function} callback   The callback method is invoked with three
+   *
+   * Syntax:
+   *
+   *    math.map(x, callback)
+   *
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.map([1, 2, 3], function(value) {
+   *      return value * value;
+   *    });  // returns [1, 4, 9]
+   *
+   * @param {Matrix | Array} x    The matrix to iterate on.
+   * @param {Function} callback   The callback method is invoked with three
    *                              parameters: the value of the element, the index
-   *                              of the element, and the Matrix being traversed.
-   * @return {Matrix/array} container
+   *                              of the element, and the matrix being traversed.
+   * @return {Matrix | array}     Transformed map of x
    */
   math.map = function (x, callback) {
     if (arguments.length != 2) {

lib/function/utils/print.js

@@ -13,22 +13,32 @@ module.exports = function (math) {
    *
    * Example usage:
    *
+   *     var math = mathjs();
+   *
+   *     // the following outputs: 'Lucy is 5 years old'
+   *     math.print('Lucy is $age years old', {age: 5});
+   *
    *     // the following outputs: 'The value of pi is 3.141592654'
-   *     math.format('The value of pi is $pi', {pi: math.pi}, 10);
+   *     math.print('The value of pi is $pi', {pi: math.pi}, 10);
    *
    *     // the following outputs: 'hello Mary! The date is 2013-03-23'
-   *     math.format('Hello $user.name! The date is $date', {
+   *     math.print('Hello $user.name! The date is $date', {
    *       user: {
    *         name: 'Mary',
    *       },
-   *       date: new Date().toISOString().substring(0, 10)
+   *       date: new Date(2013, 2, 23).toISOString().substring(0, 10)
    *     });
    *
-   * @param {String} template
-   * @param {Object} values
+   * See also:
+   *
+   *     format
+   *
+   * @param {String} template     A string containing variable placeholders.
+   * @param {Object} values       An object containing variables which will
+   *                              be filled in in the template.
    * @param {Number} [precision]  Number of digits to format numbers.
    *                              If not provided, the value will not be rounded.
-   * @return {String} str
+   * @return {String} Interpolated string
    */
   math.print = function print (template, values, precision) {
     var num = arguments.length;

lib/function/utils/typeof.js

@@ -9,13 +9,22 @@ module.exports = function (math) {
       Help = require('../../type/Help');
 
   /**
-   * Determines the type of a variable.
+   * Determine the type of a variable.
    *
    * Syntax:
    *
-   *     math.typeof(x)
+   *    math.typeof(x)
    *
-   * @param {*} x
+   * Examples:
+   *
+   *    var math = mathjs();
+   *
+   *    math.typeof(3.5);             // returns 'number'
+   *    math.typeof(2 - 4i);          // returns 'complex'
+   *    math.typeof(45 deg);          // returns 'unit'
+   *    math.typeof("hello world");   // returns 'string'
+   *
+   * @param {*} x  The variable for which to test the type.
    * @return {String} Lower case type, for example 'number', 'string', 'array'.
    */
   math['typeof'] = function _typeof (x) {

tools/docgenerator.js

@@ -279,7 +279,7 @@ function validateDoc (doc) {
     issues.push('function "' + doc.name + '": parameters missing');
   }
 
-  if (doc.returns) {
+  if (Object.keys(doc.returns).length > 0) {
     if (!doc.returns.description || !doc.returns.description.trim()) {
       issues.push('function "' + doc.name + '": description missing of returns');
     }