Add description to differentiate between token count / balance

Author: njgheorghita

docs/examples.rst

@@ -329,26 +329,33 @@ Fetch various data about the current state of the ERC20 contract.
 
 .. code-block:: python
 
-    name = erc20.functions.symbol().name()
-    # -> 🦄
+    name = erc20.functions.name().call()
+    # -> "Unicorns"
     symbol = erc20.functions.symbol().call()
-    # -> 🦄
+    # -> "🦄"
     decimals = erc20.functions.decimals().call()
     # -> 1
     total_supply = erc20.functions.totalSupply().call()
     # -> 2038 (at time of writing)
 
-Get the balance of an account address. (token balance is *always* an integer)
+Get the balance of an account address. 
 
 .. code-block:: python
 
     balance = erc20.functions.balanceOf('0xD1220A0cf47c7B9Be7A2E6BA89F429762e7b9aDb').call()
     # -> 1
 
-Calculate the token count from the token balance of an account address. (token count *may* be a fraction)
+Calculate the token count from the token balance of an account address.
 
 .. code-block:: python
+   
+    from decimal import Decimal
     
-    count = balance / (10 ** decimals)
+    # Most applications expect *exact* results, so using the Decimal library,
+    # with default precision of 28, is usually sufficient to avoid any rounding error.
+    count = balance / Decimal(10 ** decimals)
     # -> 1
 
+Balance is *always* an integer in the currency's smallest natural unit (i.e. `wei` for ether). Token balance is typically used only for backend calculations.
+
+Token count *may* be a integer or fraction in the currency's primary unit (i.e. `eth` for ether). Token count is typically displayed to the user on the front-end since it is more readable.