[doc] add some missing function/class documentation

scheme/link.py

@@ -40,11 +40,13 @@ def get_next_link_free_id():
 
 class Link(object):
     """
+    Define a link between two node with an execution order. Sink_node will be
+    executed after source_node.
 
-    :param `.Node` source_node:
-    :param `.Node` sink_node:
-    :param str source_channel:
-    :param str sink_channel:
+    :param `.Node` source_node: upstream node
+    :param `.Node` sink_node: downstream node
+    :param str source_channel: channel name used for connection
+    :param str sink_channel: channel name used for connection
     """
 
     def __init__(self, source_node, sink_node, source_channel, sink_channel,

scheme/node.py

@@ -112,12 +112,28 @@ class Node(object):
         return self._process_pt
 
     def isfinal(self):
+        """
+
+        :return: True if the node is at the end of a branch.
+        :rtype: bool
+        """
         return len(self.downstream_nodes) is 0
 
     def isstart(self):
+        """
+
+        :return: True if the node does not requires any input
+        :rtype: bool
+        """
         return len(self.upstream_nodes) is 0
 
     def load_handlers(self):
+        """
+        load handlers from the `processing_pt` defined.
+        For callable it will always be `processing_pt`.
+        But for not-callable class it will be class function defined in the
+        `inputs` variable.
+        """
         self._handlers.clear()
         assert self._process_pt is not None
         if callable(self._process_pt):
@@ -158,6 +174,18 @@ class Node(object):
 
     @staticmethod
     def execute(process_pt, properties, input_name, input_data):
+        """
+        Create an instance of a node with 'process_pt' and execute it with the
+        given input_name, properties and input_data.
+
+        :param str process_pt: name of the process to execute
+         (can be a module.class name, or a module.function)
+        :param dict properties: process properties
+        :param str input_name: name of the input data
+        :param input_data: input data :warning: Should be serializable
+
+        :return: output data. :warning: Should be serializable
+        """
         node = Node(processing_pt=process_pt, properties=properties)
         node.load_handlers()
         if input_name in node.handlers:

scheme/parser.py

@@ -48,6 +48,12 @@ class Parser(object):
 
     @staticmethod
     def get_aliases():
+        """
+
+        :return: the list of aliases for a processing_pt (module.class or
+                 module.function name)
+        :rtype: dict
+        """
         aliases = {}
         try:
             import pypushflowaddon

scheme/scheme.py

@@ -82,6 +82,12 @@ class Scheme(object):
         return res
 
     def start_nodes(self):
+        """
+
+        :return: list of nodes starting the workflow. Those does not require
+        any input_data
+        :rtype: list
+        """
         res = []
         for node in self.nodes:
             assert isinstance(node, Node)
@@ -90,6 +96,11 @@ class Scheme(object):
         return res
 
     def endlessNodes(self):
+        """
+
+        :return: list of final nodes.
+        :rtype: list
+        """
         res = []
         for node in self.nodes:
             assert isinstance(node, Node)
@@ -100,6 +111,10 @@ class Scheme(object):
     def save_to(self, output_file):
         """
         Save the scheme as an xml formated file to `stream`
+
+        :param output_file: name of the output file. For now only manage xml
+                            files
+        :type: str
         """
         tree = self.scheme_to_etree(data_format="literal")
         indent(tree.getroot(), 0)
@@ -202,8 +217,11 @@ class Scheme(object):
             node.upstream_nodes = set()
 
     def has_final_join(self):
-        """True if we need to send a 'end' signal before closing the workflow
-        This is needed for DataList and DataWatcher
+        """
+        :return: True if we need to send a 'end' signal before closing the
+                 workflow. This is needed in the 'acquisition workflow' like
+                 tomwer and the DataWatcher process for example.
+        :rtype: bool
         """
         for node in self.nodes:
             if node.need_stop_join:
@@ -212,6 +230,12 @@ class Scheme(object):
 
     @staticmethod
     def from_desc(desc):
+        """
+
+        :param desc:
+        :return: instance of Scheme from it description.
+        :rtype: :class:`Scheme`
+        """
         nodes = []
         nodes_dict = {}
 
@@ -241,6 +265,9 @@ class Scheme(object):
         return scheme
 
     def load_handlers(self):
+        """
+        load all nodes handlers.
+        """
         for node in self.nodes:
             node.load_handlers()