Improved doc strings

git-svn-id: https://svn.erp5.org/repos/public/erp5/trunk@30633 20353a03-c40f-0410-a6d1-a30d3c3de9de

product/ERP5/interfaces/business_buildable.py

@@ -33,7 +33,13 @@ Products.ERP5.interfaces.business_buildable
 from zope.interface import Interface
 
 class IBusinessBuildable(Interface):
-  """Business Buildable interface specification"""
+  """Business Buildable interface specification
+
+  This interface is implemented by Business Path as part
+  of Business Process management. It can be used to
+  check which path in a business process can be built
+  and to trigger the build process for a given path.
+  """
 
   def isBuildable(explanation):
     """Returns True if any of the related Simulation Movement
@@ -50,12 +56,13 @@ class IBusinessBuildable(Interface):
     'explanation' is the Order or Item or Document which is the
     cause of a root applied rule in the simulation
 
-    FIXME/JPS: Not sure if this will exist some day XXX
+    NOTE (JPS): It is not sure whether this method will ever
+    be used.
     """
 
   def build(explanation):
     """Builds all related movements in the simulation
-    using the builders of Business Path
+    using the builders defined on the Business Path
 
     'explanation' is the Order or Item or Document which is the
     cause of a root applied rule in the simulation

product/ERP5/interfaces/business_completable.py

+# -*- coding: utf-8 -*-
 ##############################################################################
 #
 # Copyright (c) 2009 Nexedi SA and Contributors. All Rights Reserved.
@@ -34,11 +35,16 @@ from zope.interface import Interface
 class IBusinessCompletable(Interface):
   """Business Completable interface specification
 
-  Business states and path can be completed or partially completed.
+  This interface is implemented by Business Path and Business
+  States as part of Business Process Management. It can be
+  used to check whether a path or a state is completed, or
+  partially completed.
+
+  TODO: make sure interface can support simulation movements
   """
   def isCompleted(explanation):
     """True if all related simulation movements for this explanation
-    document are delivered and in simulation state which is considered
+    document are delivered and in a simulation state which is considered
     as finished.
 
     Completed means that it is possible to move to next step of Business Process
@@ -55,6 +61,9 @@ class IBusinessCompletable(Interface):
     are frozen.
 
     Frozen means that simulation movement cannot be modified.
+
+    NOTE: simulation movements can be frozen (ex. in stopped state) but
+    not yet completed (ex. in delivered state).
     """
 
   def getExpectedCompletionDate(task):
@@ -75,10 +84,9 @@ class IBusinessCompletable(Interface):
     """
 
   def getRemainingTradePhaseList(explanation, trade_phase_list=None):
-    """
-      Returns the list of remaining trade phases which to be done on the
-      explanation.
+    """Returns the list of remaining trade phases which to be done on the
+    explanation.
 
-      trade_phase_list -- if provided, the result is filtered by it after
-                          being collected
+    trade_phase_list -- if provided, the result is filtered by it after
+                        being collected
     """