[IMP] mis_builder: improve documentation a bit

mis_builder/models/aep.py

@@ -19,18 +19,18 @@ class AccountingExpressionProcessor(object):
         * mode is i (initial balance), e (ending balance),
           p (moves over period)
         * accounts is a list of accounts, possibly containing % wildcards
-        * an optional domain on analytic lines allowing filters on eg analytic
+        * an optional domain on move lines allowing filters on eg analytic
           accounts or journal
 
     Examples:
-        * bal[70]: balance of moves on account 70 over the period
+        * bal[70]: variation of the balance of moves on account 70
-          (it is the same as balp[70]);
+          over the period (it is the same as balp[70]);
         * bali[70,60]: initial balance of accounts 70 and 60;
         * bale[1%]: balance of accounts starting with 1 at end of period.
 
     How to use:
         * repeatedly invoke parse_expr() for each expression containing
-          accounting variables as described above; this let the processor
+          accounting variables as described above; this lets the processor
           group domains and modes and accounts;
         * when all expressions have been parsed, invoke done_parsing()
           to notify the processor that it can prepare to query (mainly
@@ -41,7 +41,7 @@ class AccountingExpressionProcessor(object):
           for the given period.
 
     How it works:
-        * by accumulating the expressions before hand, it ensure to do the
+        * by accumulating the expressions before hand, it ensures to do the
           strict minimum number of queries to the database (for each period,
           one query per domain and mode);
         * it queries using the orm read_group which reduces to a query with

mis_builder/models/mis_builder.py

@@ -73,15 +73,13 @@ def _is_valid_python_var(name):
 
 class mis_report_kpi(orm.Model):
 
-    """ A KPI is an element of a MIS report.
+    """ A KPI is an element (ie a line) of a MIS report.
 
     In addition to a name and description, it has an expression
     to compute it based on queries defined in the MIS report.
     It also has various informations defining how to render it
     (numeric or percentage or a string, a suffix, divider) and
     how to render comparison of two values of the KPI.
-    KPI are ordered inside the MIS report, as some KPI expressions
-    can depend on other KPI that need to be computed before.
     """
 
     _name = 'mis.report.kpi'
@@ -288,21 +286,17 @@ class mis_report_query(orm.Model):
 
 
 class mis_report(orm.Model):
-
     """ A MIS report template (without period information)
 
     The MIS report holds:
-    * an implicit query fetching all the account balances;
-      for each account, the balance is stored in a variable named
-      bal_{code} where {code} is the account code
-    * an implicit query fetching all the account balances solde;
-      for each account, the balance solde is stored in a variable named
-      bals_{code} where {code} is the account code
     * a list of explicit queries; the result of each query is
       stored in a variable with same name as a query, containing as list
-      of data structures populated with attributes for each fields to fetch
+      of data structures populated with attributes for each fields to fetch;
+      when queries have the group by flag and no fields to group, it returns
+      a data structure with the summed fields
     * a list of KPI to be evaluated based on the variables resulting
-      from the balance and queries
+      from the balance and queries (KPI expressions can references queries
+      and accounting expression - see AccoutingExpressionProcessor)
     """
 
     _name = 'mis.report'