From 94fa3a21dd2cc2a1b154bed2c2cbcb378135737e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E9=81=93=E8=BE=95?= <daoyuanchen.cdy@alibaba-inc.com>
Date: Wed, 4 May 2022 21:53:45 +0800
Subject: [PATCH] added API comments

---
 doc/source/core.rst                      | 11 +++++--
 federatedscope/core/configs/config.py    | 38 ++++++++++++++++++++++++
 federatedscope/core/configs/constants.py |  2 --
 federatedscope/core/monitors/monitor.py  |  3 ++
 4 files changed, 50 insertions(+), 4 deletions(-)

diff --git a/doc/source/core.rst b/doc/source/core.rst
index d684e118f..11b9c87e5 100644
--- a/doc/source/core.rst
+++ b/doc/source/core.rst
@@ -7,10 +7,17 @@ federatedscope.core.configs
 .. automodule:: federatedscope.core.configs
     :members:
 
-federatedscope.core.DAIL_fed_api
+
+federatedscope.core.monitors
+-----------------------
+
+.. automodule:: federatedscope.core.monitors
+    :members:
+
+federatedscope.core.fed_runner
 -----------------------
 
-.. automodule:: federatedscope.core.DAIL_fed_api
+.. automodule:: federatedscope.core.fed_runner
     :members:
 
 federatedscope.core.worker
diff --git a/federatedscope/core/configs/config.py b/federatedscope/core/configs/config.py
index 78832dfb3..f92ac31ef 100644
--- a/federatedscope/core/configs/config.py
+++ b/federatedscope/core/configs/config.py
@@ -7,6 +7,11 @@
 
 
 class CN(CfgNode):
+    """
+        An extended configuration system based on [yacs](https://github.com/rbgirshick/yacs).
+        The two-level tree structure consists of several internal dict-like containers to allow simple key-value access and management.
+
+    """
     def __init__(self, init_dict=None, key_list=None, new_allowed=False):
         super().__init__(init_dict, key_list, new_allowed)
         self.cfg_check_funcs = []  # to check the config values validity
@@ -15,28 +20,56 @@ def register_cfg_check_fun(self, cfg_check_fun):
         self.cfg_check_funcs.append(cfg_check_fun)
 
     def merge_from_file(self, cfg_filename):
+        """
+            load configs from a yaml file, another cfg instance or a list stores the keys and values.
+
+        :param cfg_filename (string):
+        :return:
+        """
         cfg_check_funcs = copy.copy(self.cfg_check_funcs)
         super(CN, self).merge_from_file(cfg_filename)
         self.cfg_check_funcs = cfg_check_funcs
         self.assert_cfg()
 
     def merge_from_other_cfg(self, cfg_other):
+        """
+            load configs from another cfg instance
+
+        :param cfg_other (CN):
+        :return:
+        """
         cfg_check_funcs = copy.copy(self.cfg_check_funcs)
         super(CN, self).merge_from_other_cfg(cfg_other)
         self.cfg_check_funcs = cfg_check_funcs
         self.assert_cfg()
 
     def merge_from_list(self, cfg_list):
+        """
+           load configs from a list stores the keys and values.
+
+        :param cfg_list (list):
+        :return:
+        """
         cfg_check_funcs = copy.copy(self.cfg_check_funcs)
         super(CN, self).merge_from_list(cfg_list)
         self.cfg_check_funcs = cfg_check_funcs
         self.assert_cfg()
 
     def assert_cfg(self):
+        """
+            check the validness of the configuration instance
+
+        :return:
+        """
         for check_func in self.cfg_check_funcs:
             check_func(self)
 
     def clean_unused_sub_cfgs(self):
+        """
+            Clean the un-used secondary-level CfgNode, whose `.use` attribute is `True`
+
+        :return:
+        """
         for v in self.values():
             if isinstance(v, CfgNode) or isinstance(v, CN):
                 # sub-config
@@ -49,6 +82,11 @@ def clean_unused_sub_cfgs(self):
                             del v[k]
 
     def freeze(self):
+        """
+            make the cfg attributes immutable, and save the freezed cfg_check_funcs into "self.outdir/config.yaml" for better reproducibility
+
+        :return:
+        """
         self.assert_cfg()
         self.clean_unused_sub_cfgs()
         # save the final cfg
diff --git a/federatedscope/core/configs/constants.py b/federatedscope/core/configs/constants.py
index 1f7beb236..488384008 100644
--- a/federatedscope/core/configs/constants.py
+++ b/federatedscope/core/configs/constants.py
@@ -2,8 +2,6 @@
 
     - The method `local` indicates that the clients only locally train their model without sharing any training related information
     - The method `global` indicates that the only one client locally trains using all data
-    # TODO: add fine-tune, allowing freezing para name, and be called whenever need
-
 
 """
 
diff --git a/federatedscope/core/monitors/monitor.py b/federatedscope/core/monitors/monitor.py
index b65bd3430..92195c5ab 100644
--- a/federatedscope/core/monitors/monitor.py
+++ b/federatedscope/core/monitors/monitor.py
@@ -15,6 +15,9 @@
 
 
 class Monitor(object):
+    """
+        provide the monitoring functionalities such as formatting the evaluation results into diverse metrics
+    """
     SUPPORTED_FORMS = ['weighted_avg', 'avg', 'fairness', 'raw']
 
     def __init__(