improving annotations

amended just to fix merge conflict

README.md

@@ -35,8 +35,6 @@ SELECT SUM(quantity) FROM movements WHERE Source = 'Alice'
 
 Which leads to complex and unefficient queries.
 
-
-
 The underlying idea of Inventory is to see all movements from the source's point of view and from the destination's point of view. We can say that an incoming movement increase the inventory of the destination *node* while decreasing the inventory of the node at the other side of the movement, that we call *mirror node* in Inventory API terminology.
 
 We store the movements using the following data structure:
@@ -134,7 +132,6 @@ SELECT SUM(quantity) from stock where Node='Carol' and Date <= Thursday
 ## Movements properties
 In our candy example, we abstracted many of properties that are needed on movements to represent the complexity of real business cases.
 
-
 A more realistic example could be ``20 kilograms of *sand* delivered from supplier to warehouse where the unit price is 10€``.
 
 In that example movement, supplier organisation is the *source*, warehouse is the *destination*. The *resource* is sand,  *quantity* is 20, the *quantity unit* is Kilogram, the *price* (per unit) is 10 and the *price currency* is the Euro currency. Quantity and Price properties are set on movements and we can calculate the *total price* by multiplying the quantity by the price. In that case, total price is $20*10 = 200$.
@@ -157,7 +154,7 @@ For more information check the [Movement interface documentation](https://lab.ne
 
 ## Movements categories
 
-Previous example just described a movement going from supplier to warehouse. The *physical* location of the resource changed from supplier to the warehouse, but we want to consider other parties. For example, the *ownership* might not be to the warehouse but be the headquarters organisation. We can also states things like "Mr Smith is the main contact for questions related to this sales"; this is *administration*; or "the paiment will be made on this bank account"; this is *payment*; or "this sand will be used for the project of XXX (better resource)"; this is *project* or it that "it will be used for production operations"; this is *function*; that it will be paid using a governement grant money; this is *funding*.
+Previous example just described a movement going from supplier to warehouse. The *physical* location of the resource changed from supplier to the warehouse, but we want to consider other parties. For example, the *ownership* might not be to the warehouse but be the headquarters organisation. We can also states things like "Mr Smith is the main contact for questions related to this sales"; this is *administration*; or "the payment will be made on this bank account"; this is *payment*; or "this sand will be used for the project of XXX (better resource)"; this is *project* or it that "it will be used for production operations"; this is *function*; that it will be paid using a governement grant money; this is *funding*.
 
 Movements have various source / destination categories and it seems that this list of categories depends on the kind of business being modeled. Some examples are summarized in the table below:
 
@@ -257,16 +254,16 @@ for brain in getInventoryList(node_uid=(N1.getUid(), N2.getUid()),
 - payment_filter: only take into account rows which *payment_uid* matches *payment_filter*
 - section_filter: only take into account rows which *section_uid* matches *section_filter*
 - mirror_section_filter: only take into account rows which *mirror_section_uid* matches *mirror_section_filter*
-- variation text:  only take into account rows with specified *variation_text*. It is implemented in a very far from perfect way and had poor performance. **(what is this?)**
+- variation_text:  only take into account rows with specified *variation_text*. It is implemented in a very far from perfect way and had poor performance. **(XXX: what is this?)**
 - sub_variation_text: ???
 - variation_category: only take into account rows with matching *variation* or where its *variation* is a member of this list
 - simulation_state: only take into account rows with the specified *simulation_state*
-- transit_simulation_state: only take into account rows which states are transit states **(What are transit states?)**
+- transit_simulation_state: only take into account rows which states are transit states 
 - omit_transit: do not evaluate *transit_simulation_state*
-- input_simulation_state: only take into account rows with specified *simulation_state* and *quantity > 0* **(why do we have duplicated parameters? this can be achieved by using two existing parameters, for i.e., this can be reproduced by using *omit_output* and *simulation_state*)**
-- output_simulation_state: only take into account rows with specified *simulation_state* and *quantity < 0*
-- ignore_variation: do not take into account variation in inventory calculation **(???)**
-- standardise: not implemented **(if not implemented, why documented?)**
+- input_simulation_state: only take into account rows with specified *simulation_state* and *quantity > 0* **(XXX: why do we have duplicated parameters? this can be achieved by using two existing parameters, for i.e., this can be reproduced by using *omit_output* and *simulation_state*)**
+- output_simulation_state: only take into account rows with specified *simulation_state* and *quantity < 0* **(XXX: same as line above)**
+- ignore_variation: do not take into account variation in inventory calculation **(XXX: what is this?)**
+- standardise: not implemented **(XXX: if not implemented, why documented?)**
 - omit_simulation: do not take into account simulation movements
 - only_accountable: only take into account accountable movements. Default is *True*
 - omit_input: do not take into account movement with *quantity > 0*
@@ -281,11 +278,11 @@ for brain in getInventoryList(node_uid=(N1.getUid(), N2.getUid()),
 - precision: the precision used to round quantities and prices
 - metric_type: convert results to an specific *metric_type*
 - quantity_unit: display results using this specific unit
-- transformed_resource: the resource or list of resource that can be produced using the resulting movement's resource as an input. *relative_resource_url* for each line will point to the transformed resource, while the stock will be expressed in number of the respective transformed resources **(what does this actually mean?)**
+- transformed_resource: the resource or list of resource that can be produced using the resulting movement's resource as an input. *relative_resource_url* for each line will point to the transformed resource, while the stock will be expressed in number of the respective transformed resources **(XXX: what does this actually mean?)**
 - transformed_variation_text: to be used with *transformed_resource* to refine the transformation selection only to those using variated resources as input
 
 # Inventory "documents"
-Whereas we calculate inventory by summing all the movements to date, there may be differences between the theorical stock in the database and the real stock on the warehouse floor. It is common business practice to make so called "inventory" (XXX check in dictionary) where people go on the floor and count how many items of each resources are physically present in each stock locations.
+Whereas we calculate inventory by summing all the movements to date, there may be differences between the theorical stock in the database and the real stock on the warehouse floor. It is common business practice to make so called "inventory" (XXX check in dictionary) where people go on the floor and count how many items of each resource are physically present in each stock locations.
 After this, they can input the actual values in an `Inventory` document.
 
 Let's consider an example.
@@ -333,8 +330,8 @@ linear movements
 # Example uses
 
 ## Warehouse Inventory
+
 ## Time 
-## 
 
 # Tracking API
 XXX or another doc ?