Documentation updates

docs/developer/backend.rst

@@ -5,6 +5,8 @@ Backend abstraction
 
 The container backend Zoe uses is configurable at runtime. Internally there is an API that Zoe, in particular the scheduler, uses to communicate with the container backend. This document explains the API, so that new backends can be created and maintained.
 
+Zoe assumes backends are composed of multiple nodes. In case the backend is not clustered or does not expose per-node information, it can be implemented in Zoe as exposing a single node.
+
 Package structure
 -----------------
 

docs/developer/index.rst

@@ -15,3 +15,4 @@ Developer documentation
   master-api
   scheduler
   backend
+  stats

docs/developer/stats.rst

+.. _stats:
+
+Platform and scheduler statistics
+=================================
+
+.. automodule:: zoe_master.stats
+   :members:

zoe_master/backends/base.py

@@ -27,11 +27,11 @@ class BaseBackend:
         pass
 
     def init(self, state):
-        """Initializes Swarm backend starting the event monitoring thread."""
+        """Initializes the backend. In general this includes finding the current API endpoint and opening a connection to it, negotiate the API version, etc. Here backend-related threads can be started, too. This method will be called only once at Zoe startup."""
         raise NotImplementedError
 
     def shutdown(self):
-        """Performs a clean shutdown of the resources used by Swarm backend."""
+        """Performs a clean shutdown of the resources used by Swarm backend. Any threads that where started in the init() method should be terminated here. This method will be called when Zoe shuts down."""
         raise NotImplementedError
 
     def spawn_service(self, execution: Execution, service: Service, env_subst_dict: Dict):
@@ -43,5 +43,5 @@ class BaseBackend:
         raise NotImplementedError
 
     def platform_state(self) -> ClusterStats:
-        """Get the platform state."""
+        """Get the platform state. This method should fill-in a new ClusterStats object at each call, with fresh statistics on the available nodes and resource availability. This information will be used for taking scheduling decisions."""
         raise NotImplementedError