From c74a3408cab93b98859e462c45b16d7094a34f30 Mon Sep 17 00:00:00 2001
From: Jean-Paul Smets <jp@nexedi.com>
Date: Sun, 30 May 2010 08:25:34 +0000
Subject: [PATCH] Improved documentation

git-svn-id: https://svn.erp5.org/repos/public/erp5/sandbox/amount_generator@35764 20353a03-c40f-0410-a6d1-a30d3c3de9de
---
 product/ERP5/Document/BusinessPath.py    | 48 ++++++++++++++----------
 product/ERP5/interfaces/business_path.py | 20 +++++++---
 2 files changed, 42 insertions(+), 26 deletions(-)

diff --git a/product/ERP5/Document/BusinessPath.py b/product/ERP5/Document/BusinessPath.py
index 9688f8701e..5ef93dc098 100644
--- a/product/ERP5/Document/BusinessPath.py
+++ b/product/ERP5/Document/BusinessPath.py
@@ -44,10 +44,8 @@ class BusinessPath(Path, Predicate):
   """
     The BusinessPath class embeds all information related to
     lead times and parties involved at a given phase of a business
-    process.
-
-    BusinessPath are also used as helper to build deliveries from
-    buildable movements.
+    process. BusinessPath are also the most common way to trigger
+    the build deliveries from buildable movements.
 
     The idea is to invoke isBuildable() on the collected simulation
     movements (which are orphan) during build "after select" process
@@ -60,12 +58,12 @@ class BusinessPath(Path, Predicate):
 
       Pros: global select is possible by not providing a causality_uid
       Cons: global select retrieves long lists of orphan movements which
-              are not yet buildable
-            the build process could be rather slow or require activities
+            are not yet buildable the build process could be rather
+            slow or require activities
 
     TODO:
-      - merge build implementation from erp5_bpm business template to ERP5
-        product code with backward compatibility
+    - IArrowBase implementation has too many comments which need to be
+      fixed
   """
   meta_type = 'ERP5 Business Path'
   portal_type = 'Business Path'
@@ -99,6 +97,11 @@ class BusinessPath(Path, Predicate):
                             interfaces.IPredicate,
                             )
 
+  # Helper Methods
+  def _getExplanationRelatedSimulationMovementValueList(self, explanation):
+    explanation_cache = _getExplanationCache(explanation)
+    return explanation_cache.getBusinessPathRelatedSimulationMovementValueList(self)
+
   # IArrowBase implementation
   security.declareProtected(Permissions.AccessContentsInformation,
                             'getSourceArrowBaseCategoryList')
@@ -146,11 +149,6 @@ class BusinessPath(Path, Predicate):
             #'destination_transport'
             )
 
-  # Helper Methods
-  def _getExplanationRelatedSimulationMovementValueList(self, explanation):
-    explanation_cache = _getExplanationCache(explanation)
-    return explanation_cache.getBusinessPathRelatedSimulationMovementValueList(self)
-
   # XXX-JPS UNkonwn ?
   security.declareProtected(Permissions.AccessContentsInformation,
                             'getArrowCategoryDict')
@@ -250,14 +248,18 @@ class BusinessPath(Path, Predicate):
     return method()
 
   def getCompletionDate(self, explanation):
-    """Returns the date of completion of the movemnet 
-    based on paremeters of the business path. This complete date can be
-    the start date, the stop date, the date of a given workflow transition
-    on the explaining delivery, etc.
+    """Returns the date of completion of business path in the
+    context of the explanation. The completion date of the Business 
+    Path is the max date of all simulation movements which are
+    related to the Business Path and which are part of the explanation.
 
-    XXX - DOC
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
 
-    movement -- a Simulation Movement
+    NOTE:
+    It seems that current implementation makes sense mostly in the
+    context of a root explanation.
     """
     date_list = []
     for movement in self._getExplanationRelatedSimulationMovementValueList(explanation):
@@ -357,7 +359,13 @@ class BusinessPath(Path, Predicate):
     return True
 
   def isDelivered(self, explanation):
-    """XXX
+    """Returns True is all simulation movements related to this
+    Business Path in the context of given explanation are built
+    and related to a delivery through the 'delivery' category.
+
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
     """
     for simulation_movement in self._getExplanationRelatedSimulationMovementValueList(
         explanation):
diff --git a/product/ERP5/interfaces/business_path.py b/product/ERP5/interfaces/business_path.py
index 685e39f54c..48e60710bc 100644
--- a/product/ERP5/interfaces/business_path.py
+++ b/product/ERP5/interfaces/business_path.py
@@ -60,12 +60,14 @@ class IBusinessPath(Interface):
     """
   
   def getCompletionDate(explanation):
-    """Returns the date of completion of the movemnet 
-    based on paremeters of the business path. This completion date can be
-    the start date, the stop date, the date of a given workflow transition
-    on the explaining delivery, etc.
+    """Returns the date of completion of business path in the
+    context of the explanation. The completion date of the Business 
+    Path is the max date of all simulation movements which are
+    related to the Business Path and which are part of the explanation.
 
-    XXXXXXXXXXXXXXXx
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
     """
 
   def getExpectedQuantity(amount):
@@ -126,7 +128,13 @@ class IBusinessPath(Interface):
     """
 
   def isDelivered(explanation):
-    """XXX
+    """Returns True is all simulation movements related to this
+    Business Path in the context of given explanation are built
+    and related to a delivery through the 'delivery' category.
+
+    explanation -- the Order, Order Line, Delivery or Delivery Line which
+                   implicitely defines a simulation subtree and a union 
+                   business process.
     """
 
   def build(explanation):
-- 
2.30.9