improve doc and cleanup code

frappyman.py

@@ -98,7 +98,17 @@ class FrappyManager(ServiceManager):
       <service> is one of main, stick, addons
 %(legend)s
     """
-    sea_info = None
+    # changed in all_info (see docstring there)
+    frappy2sea = None
+    sea2frappy = None
+    list_info = None
+    # changed in get_server_state:
+    frappy_cfgs = None
+    sea_cfgs = None
+    state = None
+    error = None
+    remarks = None
+    sea = None
 
     def config_dirs(self, ins, service):
         cfgpaths = []
@@ -199,7 +209,9 @@ class FrappyManager(ServiceManager):
         init(*nodes)
         interact()
 
-    def get_cfg_details(self, namespace, cfgfile):
+    @staticmethod
+    def get_cfg_details(namespace, cfgfile):
+        # get sea_cfg option from frappy cfg file
         namespace.init()
         local = {}
         with open(cfgfile, encoding='utf-8') as f:
@@ -229,8 +241,10 @@ class FrappyManager(ServiceManager):
         :param details: get details about relation to sea
         :return: see param:`what`
 
-        sea_info: is a dict <frappycfg> of <seacfg> (including extension .config/.stick/.addon)
-        list_info: dict <cfgdir> of <cfg> of <description>
+        implicit results:
+        self.frappy2sea: a dict <frappycfg> of <seacfg> (including extension .config/.stick/.addon)
+        self.sea2frappy: a dict <seacfg> of set of <frappycfg>
+        self.list_info: dict <cfgdir> of <cfg> of <description>
         """
         all_cfg = set()
         if not ins:
@@ -326,17 +340,22 @@ class FrappyManager(ServiceManager):
 
         :param ins: the instance to be checked for
         :param givencfgs: a dict <service> of cfg given by the ECS
+        :return: a dict <service> of cfg, where cfg is either:
+                - a bare string: this cfg is proposed to change to this value
+                - Reconnect(cfg): the frappy server is running as expected, but the given cfg does not match
+                - Keep(cfg): no change needed
+                remark: Reconnect amd Keep inherit from str, so Reconnect(cfg) == cfg is always True
 
-        TODO: update this doc
-        :return: tuple (<error>, <proposed>, (<frappyitems>, <seaitems>), <remarks> where:
-            <error>: proposed config not sure
-            <proposed>: dict <service> of proposed cfg
-            <frappyitems>: dict of items running in frappy servers (addons are separated)
-            <seaitems>: dict of items running on the sea server
-            <remarks>: dict of actions to do / remarks
+        implicit results:
+        self.remarks: a dict <service> of remark (why should this be changed?)
+        self.frappy_cfgs: a dict <service> of running cfgs
+        self.sea_cfgs: a dict <service> of sea cfgs (without ending .config/.stick/.addon)
+        self.state: a dict ('sea <service>' | 'frappy <service>') of cfg summarizing the state of all servers
+                    a change of self.state indicates that the configuration may need to be reevaluated
+        self.error: there is an ambiguity for the mapping seacfg -> frappycfg
+        self.sea: a fresh SeaManager instance
         """
         self.frappy_cfgs = self.get_cfg(ins, None)  # dict <service> of running frappy servers
-
         self.sea = SeaManager()
         seaconfig = self.sea.get_cfg(ins, 'sea')
         sealist = seaconfig.split('/')  # <config>, <stick>, <addon1>, <addon2> ...