Fix fromWei / toWei param and return type documentation (#3115)

* Fixing Documentation of fromWei and toWei

* Add unit tests for fromWei/toWei return types

Author: cgewecke

docs/web3-utils.rst

@@ -975,7 +975,7 @@ Converts any `ether value <http://ethdocs.org/en/latest/ether.html>`_ value into
 Parameters
 ----------
 
-1. ``number`` - ``String|Number|BN``: The value.
+1. ``number`` - ``String|BN``: The value.
 2. ``unit`` - ``String`` (optional, defaults to ``"ether"``): The ether to convert from. Possible units are:
     - ``noether``: '0'
     - ``wei``: '1'
@@ -1009,7 +1009,7 @@ Parameters
 Returns
 -------
 
-``String|BN``: If a number, or string is given it returns a number string, otherwise a `BN.js <https://github.com/indutny/bn.js/>`_ instance.
+``String|BN``: If a string is given it returns a number string, otherwise a `BN.js <https://github.com/indutny/bn.js/>`_ instance.
 
 -------
 Example
@@ -1049,7 +1049,7 @@ Converts any `wei <http://ethereum.stackexchange.com/questions/253/the-ether-den
 Parameters
 ----------
 
-1. ``number`` - ``String|Number|BN``: The value in wei.
+1. ``number`` - ``String|BN``: The value in wei.
 2. ``unit`` - ``String`` (optional, defaults to ``"ether"``): The ether to convert to. Possible units are:
     - ``noether``: '0'
     - ``wei``: '1'
@@ -1083,7 +1083,7 @@ Parameters
 Returns
 -------
 
-``String|BN``: If a number, or string is given it returns a number string, otherwise a `BN.js <https://github.com/indutny/bn.js/>`_ instance.
+``String``: It always returns a string number.
 
 -------
 Example

test/utils.fromWei.js

@@ -27,5 +27,13 @@ describe('lib/utils/utils', function () {
                 assert(error.message.includes('Please pass numbers as strings or BN objects'))
             }
         })
+        // fromWei always returns string
+        it('should return the correct type', function(){
+            var weiString = '100000000000000000';
+            var weiBN = utils.toBN(weiString);
+
+            assert(typeof utils.fromWei(weiString) === 'string');
+            assert(typeof utils.fromWei(weiBN) === 'string');
+        })
     });
 });

test/utils.toWei.js

@@ -35,13 +35,25 @@ describe('lib/utils/utils', function () {
             assert.throws(function () {utils.toWei(1, 'wei1');}, Error);
         });
 
+
         it('should verify "number" arg is string or BN', function () {
             try {
                 utils.toWei(1, 'wei')
                 assert.fail();
             } catch (error) {
                 assert(error.message.includes('Please pass numbers as strings or BN objects'))
             }
+        });
+
+        // toWei returns string when given string, BN when given BN
+        it('should return the correct type', function(){
+            var weiString = '1';
+            var weiBN = utils.toBN(weiString);
+
+            var bn = utils.toWei(weiBN);
+
+            assert(utils.isBN(bn));
+            assert(typeof utils.toWei(weiString) === 'string');
         })
     });
 });