Add docstrings

script_mac.py

@@ -41,8 +41,14 @@ class ErrorRep(object):
 
 
 def logical_operator(elements, operator):
-    """
-    @return logical_formula: str - AND/OR of the input list
+    """Join elements with the given logical operator.
+
+    :param arg1: Iterable of elements to join with a logical operator
+    :param arg2: Logical operator to use 'and' or 'or'
+    :return: logical_formula: str - AND/OR of the input list
+    :type arg1: <list>
+    :type arg2: <str>
+    :rtype: <str>
     """
     assert operator in ('and', 'or')
 #    print(operator + ": elements:", elements)
@@ -51,11 +57,21 @@ def logical_operator(elements, operator):
 
 
 def make_logical_formula(previous_frontier_places, start_prop):
-    """Make a logical formula based on previous results of MAC
+    """Make a logical formula based on previous results of MAC.
+
+    The aim is to exclude previous solution.
+
     1 line: ex: "A B" => (A and B)
     another line: ex: "B C" => (B and C)
     merge all lines: (A and B) or (B and C)
     forbid all combinaisons: not((A and B) or (B and C))
+
+    :param arg1: Set of previous frontier places (previous solutions).
+    :param arg2: Original property (constraint) for the solver.
+    :return: A logical formula which excludes all the previous solutions.
+    :type arg1: <set>
+    :type arg2: <str>
+    :rtype: <str>
     """
 
     logical_and = partial(logical_operator, operator='and')
@@ -85,6 +101,25 @@ def main2(chart_file, cam_file, cam_step_file, cam_complete_file, cam_strong_fil
           steps, final_prop, start_prop, inv_prop):
     """
 
+    :param arg1: Model file (bcx, xml, cal).
+    :param arg2: File used to store Minimal Activation Condition (MAC/CAM).
+    :param arg3: File used to store Minimal step numbers for each solution.
+    :param arg4: File used to store MAC & trajectories.
+    :param arg5: ???
+    :param arg6: Maximal steps to reach the solutions.
+    :param arg7: Formula: Property that the solver looks for.
+    :param arg8: Formula: Original property (constraint) for the solver.
+    :param arg9: Formula: ???
+    :type arg1: <str>
+    :type arg2: <str>
+    :type arg3: <str>
+    :type arg4: <str>
+    :type arg5: <str>
+    :type arg6: <int>
+    :type arg7: <str>
+    :type arg8: <str>
+    :type arg9: <str>
+
     .. todo: handle these QUERY PARAMETERS... from GUI program
 
             #    if self.possible:
@@ -96,7 +131,6 @@ def main2(chart_file, cam_file, cam_step_file, cam_complete_file, cam_strong_fil
             #        if len(inv_prop) != 0:
             # sert pas:
             #            final_prop = "not ("+final_prop+" and "+inv_prop+")"
-
     """
 
     # Build MCLA
@@ -194,6 +228,8 @@ def find_mac(mcla,
 def detect_model_type(mclanalyser, filepath):
     """Return the function to use to load the model.
 
+    The detection is based on the file extension.
+
     bcx file: Build an MCLAnalyser from a .bcx file:
         build_from_chart_file()
     cal file: Build an MCLAnalyser from a .cal file of PID database
@@ -201,6 +237,12 @@ def detect_model_type(mclanalyser, filepath):
     xml file: Build an MCLAnalyser from a .xml file of PID database:
         build_from_pid_file()
 
+    :param arg1: MCLAnalyser.
+    :param arg2: File that contains the model.
+    :type arg1: <MCLAnalyser>
+    :type arg2: <str>
+    :return: The function to use to read the given file.
+    :rtype: <func>
     """
 
     build_func = {".bcx": mclanalyser.build_from_chart_file,
@@ -310,16 +352,21 @@ def main(chart_file, cam_file, cam_step_file, cam_complete_file, cam_strong_file
 
 
 def launch_researchs(args):
-    """
+    """Parse arguments and launch multiprocessing if an input file was specified
 
+    - If there is no input file, there will be only on process.
+    - If an input file is given, there will be 1 process per line (per logical
+    formula on each line).
     """
 
     params = args_to_param(args)
 
+    # No input file
     if params['final_prop']:
         compute_macs(params)
 
-
+    # Multiple properties in input file
+    # => multiprocessing: 1 process for each property
     else:
 
         with open(params['input_file'], 'r') as fd:
@@ -327,9 +374,9 @@ def launch_researchs(args):
 
             final_properties = [prop for prop in g if prop != '']
 
-        print(final_properties)
+        LOGGER.debug("Final properties: " + str(final_properties))
 
-        def change_args(prop):
+        def update_params(prop):
 
             d = params.copy()
             d['final_prop'] = prop
@@ -338,7 +385,7 @@ def launch_researchs(args):
         with ProcessPoolExecutor(max_workers=mp.cpu_count()) as e:
 
             futures_and_output = {e.submit(compute_macs,
-                                            change_args(job_property)
+                                           update_params(job_property)
                                           ):job_property \
                                 for job_property in final_properties} # Job name
 
@@ -368,13 +415,18 @@ def launch_researchs(args):
 
 
 def compute_macs(params):
-    """Launch Cadbiom search of MACs (Minimal Activation Conditions)"""
+    """Launch Cadbiom search of MACs (Minimal Activation Conditions).
+
+    This function is called 1 or multiple times according to the necessity
+    to use multiprocessing (Cf launch_researchs()).
+
+    .. note:: Previous result files will be deleted.
+
+    """
 
     # Limit recursion
     sys.setrecursionlimit(10000)
 
-#    params = args_to_param(args)
-
     # QUERY PARAMETERS
     # Todo beware with type of separators in path..
     MODEL_NAME = params['chart_file'].split('/')[-1][:-4]
@@ -487,6 +539,7 @@ if __name__ == "__main__":
                                               help=compute_macs.__doc__)
     parser_input_file.add_argument('chart_file')
 #    parser_input_file.add_argument('final_prop')
+    # Get final_property alone OR an input_file containing multiple properties
     group = parser_input_file.add_mutually_exclusive_group()
     group.add_argument('final_prop', nargs='?')
     group.add_argument('--input_file', action=ReadableFile, nargs='?')