touch up ‘Amount’, ‘SignedAmount’ section

- use new section heading
- rework first para
  - move format to example block
  - mention aka ‘CUR:X.Y’
- revamp "import" line, plus references

1 files changed, 15 insertions, 9 deletions

diff --git a/doc/doc.org b/doc/doc.org
index e0905db..b1be861 100644
--- a/doc/doc.org
+++ b/doc/doc.org
@@ -47,11 +47,17 @@ The rest are /leaf classes/.
 - SectionDict(collections.defaultdict)
 - TalerConfig
 
-* classes =Amount=, =SignedAmount=
+* classes for handling currency plus value plus fraction
 
-These classes handle Taler /amounts/, objects referred to in the format
-=CURRENCY:VALUE.FRACTION=, where =CURRENCY= is the currency designation
-abbreviation (e.g., "KUDOS"), and =VALUE= and =FRACTION= are integers.
+The =Amount= and =SignedAmount= handle Taler /amounts/,
+objects that combine a =CURRENCY= (e.g., "KUDOS")
+with a =VALUE= and =FRACTION= (both integers).
+An amount is written as follows:
+
+: CURRENCY:VALUE.FRACTION
+
+Note the =:= (colon) and =.= (period).
+This is also known as the =CUR:X.Y= format.
 
 The maximum =VALUE= is 2^52 (i.e., 4503599627370496).
 The =FRACTION= can be at most 8 digits (i.e., smallest non-zero
@@ -64,9 +70,9 @@ the constructor throws an =AmountOverflowError= exception.
 
 The constructor takes three args: /currency/, /value/, /fraction/.
 
-: >>> from taler.util import amount
+: >>> from taler.util.amount import Amount, SignedAmount
 : # KUDOS 10.50
-: >>> amt = amount.Amount ("KUDOS", 10, 50000000)
+: >>> amt = Amount ("KUDOS", 10, 50000000)
 : >>> amt
 : Amount(currency='KUDOS', value=10, fraction=50000000)
 
@@ -79,7 +85,7 @@ You can use classmethod =parse= to read a string as an =Amount= object.
 This function can throw =AmountFormatError= if the string is malformed,
 and =AmountOverflowError= if the fraction portion is too long.
 
-: >>> amount.Amount.parse ("KUDOS:10.12345678")
+: >>> Amount.parse ("KUDOS:10.12345678")
 : Amount(currency='KUDOS', value=10, fraction=12345678)
 
 An =Amount= object supports addition and subtraction.
@@ -88,7 +94,7 @@ a =CurrencyMismatchError= exception.
 
 : >>> amt + amt
 : Amount(currency='KUDOS', value=21, fraction=0)
-: >>> another = amount.Amount ("KUDOS", 5, 42)
+: >>> another = Amount ("KUDOS", 5, 42)
 : >>> amt - another
 : Amount(currency='KUDOS', value=5, fraction=49999958)
 
@@ -165,7 +171,7 @@ The classmethod =parse= recognizes a leading =+= or =-=, and
 additionally accepts a plain =CURRENCY:VALUE.FRACTION= form as a
 positive =SignedAmount=.
 
-: >>> amount.SignedAmount.parse ("-KUDOS:2.34")
+: >>> SignedAmount.parse ("-KUDOS:2.34")
 : SignedAmount(is_positive=False, amount=Amount(currency='KUDOS', value=2, fraction=34000000))
 
 Lastly, a =SignedAmount= object can flip its sign using a unary minus.