调整 fastNLP/core/callbacks 中的部分文档格式

fastNLP/core/callbacks/callback.py

@@ -10,7 +10,7 @@ from .callback_event import Event, Filter
 
 class Callback:
     r"""
-    实际使用的 callback 类，不管是我们 fastNLP 默认提供的一些 callback 类，还是用户自己定制的 callback 类，都应该继承该基类；
+    实际使用的 callback 类，不管是 **fastNLP** 默认提供的一些 callback 实例，还是用户自己定制的 callback 类，都应该继承该基类；
     callback 调用时机顺序大概如下::
 
         Trainer.__init__():
@@ -41,17 +41,17 @@ class Callback:
             finally:
                 on_train_end(trainer)
 
-    其它 callback 例如 on_evaluate_begin(trainer)/on_evaluate_end(trainer, results)/on_save_model(trainer)/
-    on_load_model(trainer)/on_save_checkpoint(trainer)/on_load_checkpoint(trainer)将根据需要在Trainer.run()中特定
-    的时间调用。
+    其它 callback 例如 **on_evaluate_begin(trainer)** / **on_evaluate_end(trainer, results)** / **on_save_model(trainer)** / 
+    **on_load_model(trainer)** / **on_save_checkpoint(trainer)** / **on_load_checkpoint(trainer)** 将根据需要在 :meth:`fastNLP.Trainer.run` 
+    中特定的时间调用。
     """
 
     def on_after_trainer_initialized(self, trainer, driver):
         r"""
-        在 `Trainer` 初始化后会被触发；
+        在 ``Trainer`` 初始化后会被触发；
 
-        :param trainer: ``Trainer`` 实例；
-        :param driver: ``Trainer`` 中的 ``driver`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param driver: :class:`~fastNLP.Trainer` 中的 ``driver`` 实例；
         """
         pass
 
@@ -59,7 +59,7 @@ class Callback:
         r"""
         在 '预跑'检测 开始前会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -67,7 +67,7 @@ class Callback:
         r"""
         在 '预跑'检测 开始后会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         :param sanity_check_res: 预跑得到的评测结果，关于对于 **预跑** 的解释，请见 :meth:`~fastNLP.core.controllers.trainer.Trainer.run`；
         """
         pass
@@ -76,7 +76,7 @@ class Callback:
         r"""
         在训练开始前会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -84,7 +84,7 @@ class Callback:
         r"""
         在训练完成后会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -92,7 +92,7 @@ class Callback:
         r"""
         在训练过程中的每一个 epoch 开始前会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -100,7 +100,7 @@ class Callback:
         r"""
         在训练过程中的每一个 epoch 完成后会被触发；此时 trainer.cur_epoch_idx 已经完成加 1 操作。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -108,7 +108,7 @@ class Callback:
         r"""
         在训练过程中准备取出下一个 batch 的数据时触发
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -116,30 +116,30 @@ class Callback:
         r"""
         在训练过程中拿到当前的 batch 数据后会被触发；
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
     def on_train_batch_begin(self, trainer, batch, indices):
         r"""
-        在取得数据，执行完 ``input_mapping`` (如果 ``Trainer`` 传有该参数），并且移动 ``batch`` 中的 ``tensor`` 到了指定设备。
+        在取得数据，执行完 ``input_mapping`` (如果 :class:`~fastNLP.Trainer` 传有该参数），并且移动 ``batch`` 中的张量到了指定设备之后会被触发。
         其中 ``batch`` 中的数据格式要么是 ``Dataloader`` 返回的每个 ``batch`` 的格式；要么是 ``input_mapping`` 之后的内容。
-        如果 ``batch`` 是 ``dict`` 类型，直接增删其中的 ``key`` 或 修改其中的 ``value`` 会影响到输入到 ``model`` 的中的 ``batch`` 数据。
+        如果 ``batch`` 是 ``dict`` 类型，直接增删其中的 key 或 修改其中的 value 会影响到输入模型的中的 ``batch`` 数据。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         :param batch: batch 的数据，已经经过 ``input_mapping`` (如果有) 以及移动到指定设备 。
-        :param list[int] indices: 当前的 ``batch`` 是 ``dataset`` 中的哪些数据。仅在 ``DataLoader`` 支持得到当前 ``batch index`` 的时候有值，
-            其它时候为 None 。
+        :param list[int] indices: 当前的 ``batch`` 是数据集中的哪些数据。仅在 ``DataLoader`` 支持得到当前 ``batch index`` 的时候有值，
+            其它时候为 ``None`` 。
         """
         pass
 
     def on_train_batch_end(self, trainer):
         r"""
-        完成一个 batch 的训练（forward）、梯度回传（backward）、梯度更新（step）、梯度置零、batch_idx_in_epoch与
-        global_forward_batches累计加1操作。其中梯度更新】梯度置零操作会考虑 accumulation_steps ，所以不一定在当前 batch 会
+        完成一个 batch 的训练（forward）、梯度回传（backward）、梯度更新（step）、梯度置零、batch_idx_in_epoch 与
+        global_forward_batches 累计加1操作之后会被触发。其中梯度更新、梯度置零操作会考虑 **accumulation_steps** ，所以不一定在当前 batch 会
         执行。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -147,41 +147,41 @@ class Callback:
         r"""
         在训练过程遇到异常时调用。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         :param exception: 遭遇的异常；
         """
         pass
 
     def on_save_model(self, trainer):
         r"""
-        当调用 Trainer.save_model() 时调用，此刻模型还未保存。
+        当调用 :meth:`fastNLP.Trainer.save_model` 时调用，此刻模型还未保存。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
     def on_load_model(self, trainer):
         r"""
-        当调用 Trainer.load_model() 加载模型时调用，此刻模型还未加载。
+        当调用 :meth:`fastNLP.Trainer.load_model` 加载模型时调用，此刻模型还未加载。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
     def on_save_checkpoint(self, trainer) -> Dict:
         r"""
-        当 Trainer 将要保存 checkpoint 的时候触发 (即调用 Trainer.save_checkpoint() 函数时)，该函数用于保存当前 callback 在恢复需要的相关数据。
+        当 Trainer 将要保存 checkpoint 的时候触发 (即调用 :meth:`Trainer.save_checkpoint`()` 函数时)，该函数用于保存当前 callback 在恢复时需要的相关数据。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
     def on_load_checkpoint(self, trainer, states: Optional[Dict]):
         r"""
-        当 Trainer 要恢复 checkpoint 的时候触发（即调用 Trainer.load_checkpoint() 函数时, 此刻 Trainer 与 Driver 已经加载好自身
-        的状态）， 参数 states 为 Callback 在调用 on_save_checkpoint() 的返回值。
+        当 Trainer 要恢复 checkpoint 的时候触发（即调用 :meth:`Trainer.load_checkpoint` 函数时, 此刻 Trainer 与 Driver 已经加载好自身
+        的状态）， 参数 states 为 Callback 在调用 :meth:`on_save_checkpoint` 的返回值。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         :param states:
         """
         pass
@@ -190,7 +190,7 @@ class Callback:
         r"""
         在 backward 前执行。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         :param outputs: ``model`` 的返回内容。如果有 ``output_mapping``，则 ``outputs`` 中的内容为已经执行了 ``output_mapping`` 后的结果。
         """
         pass
@@ -198,54 +198,54 @@ class Callback:
     def on_after_backward(self, trainer):
         r"""
         在 ``backward`` 后执行。在多卡场景下，由于 ``accumulation_steps`` 的影响，仅在需要真正 ``update`` 参数那次梯度回传才会触发梯度同步，
-        因此在多卡且使用 ``accumulation_steps`` 时，可能存在某些 ``step`` 各卡上梯度不一致的问题。
+        因此在多卡且使用 ``accumulation_steps`` 时，可能存在某些 step 各卡上梯度不一致的问题。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
     def on_before_optimizers_step(self, trainer, optimizers):
         r"""
-        在进行 optimizer 优化进行前调用。该接口不一定每次前向计算都会触发，实际调用会受到 accumulation_steps 的影响。
+        在进行 optimizer 优化进行前调用。该接口不一定每次前向计算都会触发，实际调用会受到 ``accumulation_steps`` 的影响。
 
-        :param trainer: ``Trainer`` 实例；
-        :param optimizers: 优化器，内容为在 ``Trainer`` 初始化时传入的值。
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param optimizers: 优化器，内容为在 :class:`~fastNLP.Trainer` 初始化时传入的值。
         """
         pass
 
     def on_after_optimizers_step(self, trainer, optimizers):
         r"""
-        在进行 optimizer 优化进行后调用。该接口不一定每次前向计算都会触发，实际调用会受到 accumulation_steps 的影响。
+        在进行 optimizer 优化进行后调用。该接口不一定每次前向计算都会触发，实际调用会受到 ``accumulation_steps`` 的影响。
 
-        :param trainer: ``Trainer`` 实例；
-        :param optimizers: 优化器，内容为在 ``Trainer`` 初始化时传入的值。
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param optimizers: 优化器，内容为在 :class:`~fastNLP.Trainer` 初始化时传入的值。
         """
         pass
 
     def on_before_zero_grad(self, trainer, optimizers):
         r"""
-        在进行模型梯度置零前调用。该接口不一定每次前向计算都会触发，实际调用会受到 accumulation_steps 的影响。
+        在进行模型梯度置零前调用。该接口不一定每次前向计算都会触发，实际调用会受到 ``accumulation_steps`` 的影响。
 
-        :param trainer: ``Trainer`` 实例；
-        :param optimizers: 优化器，内容为在 ``Trainer`` 初始化时传入的值。
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param optimizers: 优化器，内容为在 :class:`~fastNLP.Trainer` 初始化时传入的值。
         """
         pass
 
     def on_after_zero_grad(self, trainer, optimizers):
         r"""
-        在进行模型梯度置零后调用。该接口不一定每次前向计算都会触发，实际调用会受到 accumulation_steps 的影响。
+        在进行模型梯度置零后调用。该接口不一定每次前向计算都会触发，实际调用会受到 ``accumulation_steps`` 的影响。
 
-        :param trainer: ``Trainer`` 实例；
-        :param optimizers: 优化器，内容为在 ``Trainer`` 初始化时传入的值。
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param optimizers: 优化器，内容为在 :class:`~fastNLP.Trainer` 初始化时传入的值。
         """
         pass
 
     def on_evaluate_begin(self, trainer):
         r"""
-        在将要进行 evaluate 时调用。如果是设置的以 step 数量 或 自定义地 决定 evaluate 的频率，该接口是在 on_train_batch_end 之后
-        进行调用。如果是以 epoch 数量决定调用，该接口是在 on_train_epoch_end 之后调用。
+        在将要进行 ``evaluate`` 时调用。如果是设置的以 step 数量或自定义地决定 evaluate 的频率，该接口是在 :meth:`on_train_batch_end` 之后
+        进行调用。如果是以 epoch 数量决定调用时机，该接口是在 :meth:`on_train_epoch_end` 之后调用。
 
-        :param trainer: ``Trainer`` 实例；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
         """
         pass
 
@@ -253,17 +253,17 @@ class Callback:
         r"""
         结束 evaluate 时调用，并把 evaluate 的结果传入。
 
-        :param trainer: ``Trainer`` 实例；
-        :param results: ``Trainer`` 内置的 ``Evaluator`` 评测的结果，通常是个 ``dict``；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param results: :class:`~fastNLP.Trainer` 内置的 ``Evaluator`` 评测的结果，通常是个 ``dict``；
         """
         pass
 
     @property
     def callback_name(self):
         r"""
-        ``callback`` 的名称，我们会使用该名称从 ``checkpoint`` 中读取的相应的 ``state`` 并传递给 ``on_load_checkpoint()`` 函数。
+        ``callback`` 的名称，我们会使用该名称从 ``checkpoint`` 中读取的相应的 ``state`` 并传递给 :meth:`on_load_checkpoint` 函数。
 
-        :return: 返回用于区分该 ``callback`` 实例的 ``name``；
+        :return: 返回用于区分该 ``callback`` 实例的名称；
         """
         return self.__class__.__name__
 

fastNLP/core/callbacks/callback_event.py

@@ -31,13 +31,13 @@ def check_legality(fn):
 
 class Event:
     """
-    与 Trainer.on 函数配合使用，达到控制 callback 函数运行时机的目的。
+    与 :meth:`Trainer.on` 函数配合使用，达到控制 callback 函数运行时机的目的。
 
-    :param value: Trainer 的 callback 时机。
-    :param int every: 触发了多少次，才真正运行一次。
-    :param bool once: 是否只在第一次运行后就不再执行了。
-    :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-        filter.num_executed 两个变量分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+    :param value: Trainer 的 callback 时机；
+    :param every: 每触发多少次才真正运行一次；
+    :param once: 在第一次运行后时候再次执行；
+    :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+        `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
     """
     every: Optional[int]
     once: Optional[int]
@@ -53,416 +53,416 @@ class Event:
         return "<event={0}, every={1}, once={2}, filter fn is:{3}>".format(self.value, self.every, self.once,
                                                                                 self.filter_fn)
     @staticmethod
-    @check_legality
     def on_after_trainer_initialized(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_after_trainer_initialized 时
+        当 Trainer 运行到 :func:`on_after_trainer_initialized` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。默认为
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_after_trainer_initialized', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_sanity_check_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_sanity_check_begin 时
+        当 Trainer 运行到 :func:`on_sanity_check_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
+        :return:
         :return:
         """
         return Event(value='on_sanity_check_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_sanity_check_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_sanity_check_end 时
+        当 Trainer 运行到 :func:`on_sanity_check_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_sanity_check_end', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_begin 时
+        当 Trainer 运行到 :func:`on_train_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_end 时
+        当 Trainer 运行到 :func:`on_train_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_end', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_epoch_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_epoch_begin 时
+        当 Trainer 运行到 :func:`on_train_epoch_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_epoch_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_epoch_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_epoch_end 时
+        当 Trainer 运行到 :func:`on_train_epoch_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_epoch_end', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_fetch_data_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_fetch_data_begin 时
+        当 Trainer 运行到 :func:`on_fetch_data_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_fetch_data_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_fetch_data_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_fetch_data_end 时
+        当 Trainer 运行到 :func:`on_fetch_data_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_fetch_data_end', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_batch_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_batch_begin 时
+        当 Trainer 运行到 :func:`on_train_batch_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_batch_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_train_batch_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_train_batch_end 时
+        当 Trainer 运行到 :func:`on_train_batch_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_train_batch_end', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_exception(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_exception 时
+        当 Trainer 运行到 :func:`on_exception` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_exception', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_save_model(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_save_model 时
+        当 Trainer 运行到 :func:`on_save_model` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_save_model', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_load_model(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_load_model 时
+        当 Trainer 运行到 :func:`on_load_model` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_load_model', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_save_checkpoint(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_save_checkpoint 时
+        当 Trainer 运行到 :func:`on_save_checkpoint` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_save_checkpoint', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_load_checkpoint(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_load_checkpoint 时
+        当 Trainer 运行到 :func:`on_load_checkpoint` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_load_checkpoint', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_load_checkpoint(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_load_checkpoint 时
+        当 Trainer 运行到 :func:`on_load_checkpoint` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_load_checkpoint', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_before_backward(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_before_backward 时
+        当 Trainer 运行到 :func:`on_before_backward` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_before_backward', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_after_backward(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_after_backward 时
+        当 Trainer 运行到 :func:`on_after_backward` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_after_backward', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_before_optimizers_step(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_before_optimizers_step 时
+        当 Trainer 运行到 :func:`on_before_optimizers_step` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_before_optimizers_step', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_after_optimizers_step(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_after_optimizers_step 时
+        当 Trainer 运行到 :func:`on_after_optimizers_step` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_after_optimizers_step', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_before_zero_grad(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_before_zero_grad 时
+        当 Trainer 运行到 :func:`on_before_zero_grad` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_before_zero_grad', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_after_zero_grad(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_after_zero_grad 时
+        当 Trainer 运行到 :func:`on_after_zero_grad` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_after_zero_grad', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_evaluate_begin(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_evaluate_begin 时
+        当 Trainer 运行到 :func:`on_evaluate_begin` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_evaluate_begin', every=every, once=once, filter_fn=filter_fn)
 
     @staticmethod
-    @check_legality
+    
     def on_evaluate_end(every=None, once=None, filter_fn=None):
         """
-        当 Trainer 运行到 on_evaluate_end 时
+        当 Trainer 运行到 :func:`on_evaluate_end` 时触发；
 
-        以下三个参数互斥，只能设置其中一个。默认为行为等同于 every=1 。
+        以下三个参数互斥，只能设置其中一个。默认为行为等同于 ``every=1`` 。
 
-        :param int every: 触发了多少次，才真正运行一次。
-        :param bool once: 是否只在第一次运行后就不再执行了。
-        :param Callable filter_fn: 输入参数的应该为 (filter, trainer)，其中 filter 对象中包含了 filter.num_called 和
-            filter.num_executed 两个变了分别获取当前被调用了多少次，真正执行了多少次。trainer 对象即为当前正在运行的 Trainer 。
+        :param every: 每触发多少次才真正运行一次；
+        :param once: 在第一次运行后时候再次执行；
+        :param filter_fn: 输入参数的应该为 ``(filter, trainer)``，其中 ``filter`` 对象中包含了 `filter.num_called` 和
+            `filter.num_executed` 两个变量分别获取当前被调用了多少次，真正执行了多少次；``trainer`` 对象即为当前正在运行的 Trainer；
         :return:
         """
         return Event(value='on_evaluate_end', every=every, once=once, filter_fn=filter_fn)
 
 
 class Filter:
-    def __init__(self, every: Optional[int] = None, once: Optional[bool] = None, filter_fn: Optional[Callable] = None):
-        r"""
-        通过该 `Filter` 作为函数修饰器来控制一个函数的实际的运行频率。
+    r"""
+    可以控制一个函数实际的运行频率的函数修饰器。
 
-        :param every: 表示一个函数隔多少次运行一次；
-        :param once: 表示一个函数只运行一次；
-        :param filter_fn: 用户定制的频率控制函数；注意该函数内部的频率判断应当是无状态的，除了参数 `self.num_called` 和
-         `self.num_executed` 外，因为我们会在预跑后重置这两个参数的状态；
-        """
+    :param every: 表示一个函数隔多少次运行一次；
+    :param once: 表示一个函数是否只运行一次；
+    :param filter_fn: 用户定制的频率控制函数；注意该函数内部的频率判断应当是无状态的，除了参数 `self.num_called` 和
+        `self.num_executed` 外，因为我们会在预跑后重置这两个参数的状态；
+    """
+    def __init__(self, every: Optional[int] = None, once: Optional[bool] = None, filter_fn: Optional[Callable] = None):
         # check legality
         check_legality(lambda *args,**kwargs:...)(every, once, filter_fn)
         if (every is None) and (once is None) and (filter_fn is None):

fastNLP/core/callbacks/callback_manager.py

@@ -75,12 +75,13 @@ class CallbackManager:
 
     def __init__(self, callbacks: Optional[List[Callback]]):
         r"""
-        注意 callback 的调用顺序：
+        注意 callback 的调用顺序为：
+
             1. 通过函数修饰器 `Trainer.on` 添加的 callback 函数；
             2. 通过 `Trainer` 的参数 `callbacks` 添加的 callback 类；
             3. 通过 `Trainer.add_callback_fn` 添加的 callback 函数；
 
-        :param callbacks: 初始化时可以传入的一系列 callback 类，通常为用户在初始化 ``Trainer`` 时直接传入的 callback 类；
+        :param callbacks: 初始化时可以传入的一系列 :class:`~fastNLP.Callback` 类，通常为用户在初始化 ``Trainer`` 时直接传入的 callback 列表；
         """
         self._need_reproducible_sampler = False
 
@@ -106,12 +107,9 @@ class CallbackManager:
 
     def initialize_class_callbacks(self):
         r"""
-        在实际的运行过程中，我们是将具体的一个 callback 实例拆分为单独的一个个 callback 函数，然后将它们加在一个字典里，该字典的键值就是
+        在实际的运行过程中，我们会将具体的一个 callback 实例拆分为单独的一个个 callback 函数，然后将它们加在一个字典里，该字典的键值就是
         一个个 callback 时机，也就是 `Event` 的类别；
         如果一个 callback 类的 callback 函数并不具备任何作用，我们实际并不会将其加在字典当中；
-
-        :param callbacks:
-        :return:
         """
         for each_callback in self.class_callbacks:
             self._need_reproducible_sampler |= each_callback.need_reproducible_sampler
@@ -144,11 +142,12 @@ class CallbackManager:
         用于断点重训的 callback 的保存函数；
         该函数主要涉及两个方面：
 
-        1. callback 的状态的保存；我们会调用每一个 callback 的 `on_save_checkpoint` 方法，该方法应当返回一个字典，其中包含着
-        断点重训应当保存的状态；
+        1. callback 的状态的保存；我们会调用每一个 callback 的 :func:`on_save_checkpoint` 方法，该方法应当返回一个字典，其中包含着
+           断点重训应当保存的状态；
         2. 每一个具体的 callback 函数的 filter 的状态；
 
-        :return: 一个包含上述内容的字典:
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :return: 一个包含上述内容的字典，格式如下:
         .. code-block::
 
             {
@@ -195,11 +194,10 @@ class CallbackManager:
 
     def on_load_checkpoint(self, trainer, states: Dict):
         r"""
-        用于断点重训的加载函数；
-        对应于断点重训的保存函数；
+        用于断点重训的加载函数，对应于断点重训的保存函数；
 
-        :param trainer: `Trainer`
-        :param states: 见 `on_save_checkpoint` 函数的返回值；
+        :param trainer: :class:`~fastNLP.Trainer` 实例；
+        :param states: 同 :func:`on_save_checkpoint` 函数的返回值；
         """
 
         # 1. 先恢复每一个具体的 callback 函数的 filter 的状态；

fastNLP/core/callbacks/checkpoint_callback.py

@@ -24,7 +24,7 @@ class CheckpointCallback(Callback):
                 - {save_object}-epoch_{epoch_idx}-batch_{global_batch_idx}-exception_{exception_type}/  # exception时保存。
                 - {save_object}-epoch_{epoch_idx}-batch_{global_batch_idx}-{monitor}_{monitor_value}/  # 满足topk条件存储文件名
 
-    model_save_fn 为 None ，则以上每个 folder 中，将生成 fastnlp_model.pkl.tar 文件。若 model_save_fn 不为 None，
+    ``model_save_fn`` 为 ``Non``e ，则以上每个 folder 中，将生成 fastnlp_model.pkl.tar 文件。若 ``model_save_fn`` 不为 ``None``，
     则 fastNLP 将 folder 绝对路径传递给该函数，fastNLP 在该 folder 下不进行模型保存。默认情况下，本 checkpoint 只保存了 model
     的状态；如还需保存 Trainer 的状态以断点重训的话，请使用 ``save_object='trainer'`` 。
 
@@ -42,18 +42,18 @@ class CheckpointCallback(Callback):
         时间戳文件夹中。如果为 None ，默认使用当前文件夹。
     :param every_n_epochs: 多少个 epoch 保存一次。
     :param every_n_batches: 多少个 batch 保存一次。
-    :param last: 如果为 True ，将在每次 epoch 运行结束都保存一次，会覆盖之前的保存。如果为 False 则不会保存 {save_object}-last 文件
-    :param topk: 保存 monitor 结果 topK 个。
-    :param on_exceptions: 在出异常信息时，是否保存。传入需要捕获的异常的类。默认将捕获 EarlyStopException 。
+    :param last: 如果为 ``True`` ，将在每次 epoch 运行结束都保存一次，会覆盖之前的保存。如果为 ``False`` 则不会保存 ``{save_object}-last`` 文件
+    :param topk: 保存 monitor 结果中的 ``topk`` 个。
+    :param on_exceptions: 在出异常信息时，是否保存。传入需要捕获的异常的类。默认将捕获 :class:`~fastNLP.core.callbacks.EarlyStopException` 。
     :param larger_better: monitor 的值是否时越大越好。
-    :param only_state_dict: 保存模型时是否只保存 state_dict 。当 model_save_fn 不为 None 时，该参数无效。
+    :param only_state_dict: 保存模型时是否只保存 state_dict 。当 ``model_save_fn`` 不为 ``None`` 时，该参数无效。
     :param model_save_fn: 个性化的保存函数，当触发保存操作时，就调用这个函数，这个函数应当接受一个文件夹作为参数，不返回任何东西。
-        如果传入了 model_save_fn 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
+        如果传入了 ``model_save_fn`` 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
     :param save_object: 可选 ['trainer', 'model']，表示在保存时的保存对象为 ``trainer+model`` 还是 只是 ``model`` 。如果
         保存 ``trainer`` 对象的话，将会保存 :class:`~fastNLP.Trainer` 的相关状态，可以通过 :meth:`Trainer.load_checkpoint` 加载该断
         点继续训练。如果保存的是 ``Model`` 对象，则可以通过 :meth:`Trainer.load_model` 加载该模型权重。
-    :param save_evaluate_results: 是否保存 evaluate 的结果。如果为 True ，在保存 topk 模型的 folder 中还将额外保存一个
-        fastnlp_evaluate_results.json 文件，记录当前的 results。仅在设置了 topk 的场景下有用，默认为 True 。
+    :param save_evaluate_results: 是否保存 evaluate 的结果。如果为 ``True`` ，在保存 topk 模型的 folder 中还将额外保存一个
+        ``*``fastnlp_evaluate_results.json``文件，记录当前的 results。仅在设置了 ``topk`` 的场景下有用，默认为 ``True`` 。
     :param kwargs:
     """
     def __init__(self, folder: Optional[Union[str, Path]] = None, every_n_epochs: Optional[int] = None,

fastNLP/core/callbacks/fitlog_callback.py

@@ -14,9 +14,9 @@ if _module_available('fitlog'):
 class FitlogCallback(HasMonitorCallback):
     """
     自动记录 ``evaluation`` 结果到 ``fitlog`` 中。会自动记录每一次 ``evaluate`` 后的结果；同时会根据
-     ``monitor`` 记录最好的结果。另外，会自动将非 ``rank 0`` 上的 ``fitlog`` 设置为 ``debug`` 状态。同时还会在 ``fitlog`` 的
-     ``other`` 列中记录一个 ``launch_time`` ，可以通过这个数值找到当前这个脚本的在 save_folder （如果有使用其它需要保存模型的
-     ``Callback`` ，例如 :class:`~fastNLP.CheckpointCallback` ）下的文件夹名称。
+    ``monitor`` 记录最好的结果。另外，会自动将非 ``rank 0`` 上的 ``fitlog`` 设置为 ``debug`` 状态。同时还会在 ``fitlog`` 的
+    ``other`` 列中记录一个 ``launch_time`` ，可以通过这个数值找到当前这个脚本的在 save_folder （如果有使用其它需要保存模型的
+    ``Callback`` ，例如 :class:`~fastNLP.CheckpointCallback` ）下的文件夹名称。
 
     :param monitor: 监控的 metric 值。
 

fastNLP/core/callbacks/has_monitor_callback.py

@@ -26,19 +26,19 @@ class CanItemDataType(ABC):
 
 class ResultsMonitor:
     """
-    可用于监控某个数值，并通过 is_better_results() 等接口实现检测结果是否变得更好了。
+    可用于监控某个数值，并通过 :meth:`is_better_results` 等接口检测结果是否变得更好。
 
-    :param monitor: 监控的 metric 值。
+    :param monitor: 监控的 metric 值：
 
         * 为 ``None``
-         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
+         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）；
         * 为 ``str``
          尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
-         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
+         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` ；
         * 为 ``Callable``
          接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
-         的 ``monitor`` 值请返回 ``None`` 。
-    :param larger_better: monitor 是否时越大越好
+         的 ``monitor`` 值请返回 ``None`` ；
+    :param larger_better: monitor 是否为越大越好；
     """
     def __init__(self, monitor:Union[Callback, str], larger_better:bool=True):
         self.set_monitor(monitor, larger_better)
@@ -60,7 +60,7 @@ class ResultsMonitor:
 
     def itemize_results(self, results):
         """
-        将结果中有 .item() 方法的都调用一下，使得 tensor 类型的数据转为 python 内置类型。
+        执行结果中所有对象的 :meth:`item` 方法（如果没有则忽略），使得 Tensor 类型的数据转为 python 内置类型。
 
         :param results:
         :return:
@@ -69,10 +69,10 @@ class ResultsMonitor:
 
     def get_monitor_value(self, results:Dict)->Union[float, None]:
         """
-        获取 monitor 的值，如果 monitor 没有直接找到，会尝试使用 最长公共字符串算法 匹配的方式寻找。
+        获取 monitor 的值，如果 monitor 没有直接找到，会尝试使用 **最长公共字符串算法** 匹配的方式寻找。
 
-        :param results: 评测结果。
-        :return: 如果为 None ，表明此次没有找到合适的monitor
+        :param results: 评测结果；
+        :return: monitor 的值；如果为 ``None`` ，表明此次没有找到合适的monitor；
         """
         if len(results) == 0 or self.monitor is None:
             return None
@@ -100,10 +100,10 @@ class ResultsMonitor:
 
     def is_better_monitor_value(self, monitor_value: float, keep_if_better=True):
         """
-        检测 monitor_value 是否是更好的
+        检测 ``monitor_value`` 是否是更好的
 
-        :param monitor_value: 待检查的 monitor_value 。如果为 None ，返回 False
-        :param keep_if_better: 如果传入的 monitor_value 值更好，则将其保存下来。
+        :param monitor_value: 待检查的 ``monitor_value`` 。如果为 ``None`` ，返回 False；
+        :param keep_if_better: 如果传入的 ``monitor_value`` 值更好，则将其保存下来；
         :return:
         """
         if monitor_value is None:
@@ -115,10 +115,10 @@ class ResultsMonitor:
 
     def is_better_results(self, results, keep_if_better=True):
         """
-        检测给定的 results 是否比上一次更好，如果本次 results 中没有找到相关的monitor 返回 False。
+        检测给定的 ``results`` 是否比上一次更好，如果本次 results 中没有找到相关的 monitor 返回 ``False``。
 
-        :param results: evaluation 结果。
-        :param keep_if_better: 当返回为 True 时，是否保存到 self.monitor_value 中。
+        :param results: evaluation 结果；
+        :param keep_if_better: 当返回为 ``True`` 时，是否保存到 ``self.monitor_value`` 中；
         :return:
         """
         monitor_value = self.get_monitor_value(results)
@@ -128,7 +128,7 @@ class ResultsMonitor:
 
     def is_former_monitor_value_better(self, monitor_value1, monitor_value2):
         """
-        传入的两个值中，是否monitor_value1的结果更好。
+        传入的两个值中，是否 ``monitor_value1`` 的结果更好。
 
         :param monitor_value1:
         :param monitor_value2:
@@ -149,7 +149,7 @@ class ResultsMonitor:
     @property
     def monitor_name(self):
         """
-        返回 monitor 的名字，如果 monitor 是个 callable 的函数，则返回该函数的名称。
+        返回 monitor 的名字，如果 monitor 是个 Callable 的函数，则返回该函数的名称。
 
         :return:
         """
@@ -185,20 +185,20 @@ class ResultsMonitor:
 class HasMonitorCallback(ResultsMonitor, Callback):
     """
     该 callback 不直接进行使用，作为其它相关 callback 的父类使用，如果 callback 有使用 monitor 可以继承该函数里面实现了
-    （1）判断monitor合法性；（2）在需要时， 根据trainer的monitor设置自己的monitor名称。
+    （1）判断 monitor 合法性；（2）在需要时， 根据 trainer 的 monitor 设置自己的 monitor 名称。
 
-    :param monitor: 监控的 metric 值。
+    :param monitor: 监控的 metric 值：
 
         * 为 ``None``
-         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
+         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）；
         * 为 ``str``
          尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
-         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
+         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` ；
         * 为 ``Callable``
          接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
-         的 ``monitor`` 值请返回 ``None`` 。
-    :param larger_better: monitor 是否时越大越好
-    :param must_have_monitor: 这个 callback 是否必须有 monitor 设置。如果设置为 True ，且没检测到设置 monitor 会报错。
+         的 ``monitor`` 值请返回 ``None`` ；
+    :param larger_better: monitor 是否为越大越好；
+    :param must_have_monitor: 这个 callback 是否必须有 monitor 设置。如果设置为 ``True`` ，且没检测到设置 monitor 会报错；
     """
     def __init__(self, monitor, larger_better, must_have_monitor=False):
         super().__init__(monitor, larger_better)
@@ -230,20 +230,20 @@ class HasMonitorCallback(ResultsMonitor, Callback):
 
 class ExecuteOnceBetterMonitor(HasMonitorCallback):
     """
-    当监控的 monitor 结果更好的时候，调用 execute_fn 函数。
+    当监控的 ``monitor`` 结果更好的时候，调用 ``execute_fn`` 函数。
 
-    :param monitor: 监控的 metric 值。
+    :param monitor: 监控的 metric 值：
 
         * 为 ``None``
-         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
+         将尝试使用 :class:`~fastNLP.Trainer` 中设置 ``monitor`` 值（如果有设置）；
         * 为 ``str``
          尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
-         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
+         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` ；
         * 为 ``Callable``
          接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
-         的 ``monitor`` 值请返回 ``None`` 。
-    :param larger_better: monitor 是否时越大越好
-    :param execute_fn: 一个可执行的函数，不接受任何参数，不反回值。在 monitor 取得更好结果的时候会调用。
+         的 ``monitor`` 值请返回 ``None`` ；
+    :param larger_better: monitor 是否是越大越好；
+    :param execute_fn: 一个可执行的函数，不接受任何参数，没有返回值。在 monitor 取得更好结果的时候会调用；
     """
     def __init__(self, monitor, larger_better, execute_fn):
         super().__init__(monitor, larger_better, must_have_monitor=True)

fastNLP/core/callbacks/load_best_model_callback.py

@@ -19,25 +19,25 @@ class LoadBestModelCallback(HasMonitorCallback):
     保存最佳的 monitor 值最佳的模型，并在训练结束的时候重新加载模型，默认会在加载之后删除权重文件。仅在训练正常结束的时候才能加载
     最好的模型。
 
-    :param monitor: 监控的 metric 值。
+    :param monitor: 监控的 metric 值：
 
         * 为 ``None``
-         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
+         将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）；
         * 为 ``str``
          尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
-         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
+         使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` ；
         * 为 ``Callable``
          接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
-         的 ``monitor`` 值请返回 ``None`` 。
-    :param larger_better: 该 metric 值是否是越大越好。
+         的 ``monitor`` 值请返回 ``None`` ；
+    :param larger_better: 该 metric 值是否是越大越好；
     :param save_folder: 保存的文件夹，如果为空，则保存在内存中。不为空，则保存一份权重到文件中，当为多机训练，且本值不为空时，请确保
-        不同的机器均可访问当该路径。当 model_save_fn 不为 None 时该值一定不能为空。
-    :param only_state_dict: 是否只保存模型的参数。当 model_save_fn 不为空时，该值无效。
-    :param model_save_fn: 保存 model 的函数，与 model_load_fn 必须同时不为空。本函数的输入为一个已经创建好的文件夹，没有输出，
-        请在函数内完成对模型的保存。
-    :param model_load_fn: 加载 model 的函数，与 model_save_fn 必须同时不为空。本函数的输入为一个已经创建好的文件夹，没有输出，
-        请在函数内完成对模型的加载。
-    :param delete_after_train: 在训练结束后是否删掉模型。
+        不同的机器均可访问当该路径。当 ``model_save_fn`` 不为 None 时该值一定不能为空；
+    :param only_state_dict: 是否只保存模型的参数。当 ``model_save_fn`` 不为空时，该值无效；
+    :param model_save_fn: 保存 model 的函数，与 ``model_load_fn`` 必须同时不为空。本函数的输入为一个已经创建好的文件夹，没有输出，
+        请在函数内完成对模型的保存；
+    :param model_load_fn: 加载 model 的函数，与 ``model_save_fn`` 必须同时不为空。本函数的输入为一个已经创建好的文件夹，没有输出，
+        请在函数内完成对模型的加载；
+    :param delete_after_train: 在训练结束后是否删掉模型；
     """
     def __init__(self, monitor:Union[str, Callable]=None, larger_better:bool = True, only_state_dict:bool = True,
                  save_folder:Optional[str] = None, model_save_fn:Optional[Callable] = None,

fastNLP/core/callbacks/lr_scheduler_callback.py

@@ -7,11 +7,11 @@ __all__ = [
 
 class LRSchedCallback(Callback):
     """
-    根据 step_on 参数在合适的时机调用 scheduler 的 step 函数。
+    根据 ``step_on`` 参数在合适的时机调用 scheduler 的 step 函数。
 
-    :param scheduler: 实现了 step() 函数的对象
-    :param step_on: 可选 ['batch'， 'epoch'] 表示在何时调用 scheduler 的 step 函数。如果为 batch 的话在每次更新参数
-        之前调用；如果为 epoch 则是在一个 epoch 运行结束后调用。
+    :param scheduler: 实现了 :meth:`step` 函数的对象；
+    :param step_on: 可选 ['batch'， 'epoch'] 表示在何时调用 scheduler 的 step 函数。如果为 ``batch`` 的话在每次更新参数
+        之前调用；如果为 ``epoch`` 则是在一个 epoch 运行结束后调用；
     """
     def __init__(self, scheduler, step_on:str='batch'):
         assert hasattr(scheduler, 'step') and callable(scheduler.step), "The scheduler object should have a " \

fastNLP/core/callbacks/more_evaluate_callback.py

@@ -12,10 +12,10 @@ from .topk_saver import TopkSaver
 
 class MoreEvaluateCallback(HasMonitorCallback):
     """
-    当评测时需要调用不同的 evaluate_fn （例如在大部分生成任务中，一般使用训练 loss 作为训练过程中的 evaluate ；但同时在训练到
-    一定 epoch 数量之后，会让 model 生成的完整的数据评测 bleu 等。此刻就可能需要两种不同的 evaluate_fn ），只使用 Trainer
-    无法满足需求，可以通过调用本 callback 进行。如果需要根据本 callback 中的评测结果进行模型保存，请传入 topk 以及
-    topk_monitor 等相关参数。可以通过 evaluate_every 或 watch_monitor 控制触发进行 evaluate 的条件。
+    当评测时需要调用不同的 ``evaluate_fn`` （例如在大部分生成任务中，一般使用训练 loss 作为训练过程中的 evaluate ；但同时在训练到
+    一定 epoch 数量之后，会让 model 生成的完整的数据评测 bleu 等。此刻就可能需要两种不同的 ``evaluate_fn`` ），只使用 Trainer
+    无法满足需求，可以通过调用本 callback 进行。如果需要根据本 callback 中的评测结果进行模型保存，请传入 ``topk`` 以及
+    ``topk_monitor`` 等相关参数。可以通过 ``evaluate_every`` 或 ``watch_monitor`` 控制触发进行 evaluate 的条件。
 
     如果设置了 evaluate 结果更好就保存的话，将按如下文件结构进行保存::
 
@@ -30,7 +30,7 @@ class MoreEvaluateCallback(HasMonitorCallback):
         1. 为负数时表示每隔几个 ``epoch`` evaluate 一次；
         2. 为正数则表示每隔几个 ``batch`` evaluate 一次；
         3. 为函数时表示用户自己传入的用于控制 evaluate 的频率的函数，该函数的应该接受当前 trainer 对象作为参数，并
-        返回一个 bool 值，返回为 True 说明需要进行 evaluate ；将在每个 ``batch`` 结束后调用该函数判断是否需要 evaluate；
+           返回一个 bool 值，返回为 ``True`` 说明需要进行 evaluate ；将在每个 ``batch`` 结束后调用该函数判断是否需要 evaluate；
 
         .. note::
 
@@ -45,32 +45,41 @@ class MoreEvaluateCallback(HasMonitorCallback):
             该函数表示当每经过 1000 个 batch，``Trainer`` 中内置的 ``Evaluator`` 就会验证一次；
 
             另一个需要注意的事情在于该函数会在每一次 batch 的结尾进行调用，当该函数返回 ``True`` 时，``Evaluator`` 才会进行验证；
-    :param watch_monitor: 这个值用来表示监控的 Trainer 中的 evaluate 结果的，当该值不为 None ，evaluate_every 失效。本参数的
-        意义是，当检测到 Trainer 中 evaluate results 的 {watch_monitor} 的结果更好时，则进行一次 evaluate 。该参数有两种
-        取值: (1) str 类型，监控的 metric 值。如果在 evaluation 结果中没有找到完全一致的名称，将使用 最长公共字符串算法 找到最
-        匹配的那个作为 monitor ; (2) 也可以传入一个函数，接受参数为 evaluation 的结果(字典类型)，返回一个 float 值作为 monitor
-        的结果，如果当前结果中没有相关的monitor 值请返回 None 。
-    :param watch_monitor_larger_better: watch_monitor 是否越大越好。
-    :param evaluate_fn: 用来控制 `Evaluator` 在评测的前向传播过程中是调用哪一个函数，例如是 `model.evaluate_step` 还是
-        `model.forward`；(1) 如果该值是 None，那么我们会默认使用 `evaluate_step` 当做前向传播的函数，如果在模型中没有
-        找到该方法，则使用 `model.forward` 函数；(2) 如果为 str 类型，则尝试从 model 中寻找该方法，找不到则报错。
+    :param watch_monitor: 这个值用来表示监控的 Trainer 中的 evaluate 结果的，当该值不为 ``None`` ，``evaluate_every`` 失效。本参数的
+        意义是，当检测到 Trainer 中 evaluate results 的 ``{watch_monitor}`` 的结果更好时，则进行一次 evaluate 。该参数有两种
+        取值: 
+        
+        1. ``str`` 类型，含义为监控的 metric 值。如果在 evaluation 结果中没有找到完全一致的名称，将使用 **最长公共字符串算法** 找到最
+           匹配的那个作为 monitor ；
+        2. 一个函数，接受参数为 evaluation 的结果（字典类型），返回一个 float 值作为 monitor
+           的结果，如果当前结果中没有相关的monitor 值请返回 ``None`` ；
+    :param watch_monitor_larger_better: ``watch_monitor`` 是否越大越好；
+    :param evaluate_fn: 用来控制 `Evaluator` 在评测的前向传播过程中是调用哪一个函数，例如是 :meth:`model.evaluate_step` 还是
+        :meth:`model.forward`：
+        
+        1. 如果该值是 ``None``，那么我们会默认使用 :meth:`model.evaluate_step` 当做前向传播的函数，如果
+           在模型中没有找到该方法，则使用 :meth:`model.forward` 函数；
+        2. 如果为 ``str`` 类型，则尝试从 model 中寻找该方法，找不到则报错；
     :param num_eval_sanity_batch: 在初始化 Evaluator 后运行多少个 sanity check 的 batch ，检测一下。
-    :param topk: 如果需要根据当前 callback 中的 evaluate 结果保存模型或 Trainer ，可以通过设置 tokp 实现。（1）为 -1 表示每次
-        evaluate 后都保存；（2）为 0 （默认），表示不保存；（3）为整数，表示保存性能最 topk 个。
+    :param topk: 如果需要根据当前 callback 中的 evaluate 结果保存模型或 Trainer ，可以通过设置 topk 实现：
+    
+        1. 为 ``-1`` 表示每次 evaluate 后都保存；
+        2. 为 ``0`` （默认），表示不保存；
+        3. 为整数，表示保存性能最好的 ``topk`` 个。
     :param topk_monitor: 如果需要根据当前 callback 中的 evaluate 结果保存。这个参数是指在当前 callback 中的 evaluate 结果寻找
-    :param topk_larger_better: topk_monitor 的值是否时越大越好。
+    :param topk_larger_better: ``topk_monitor`` 的值是否是越大越好。
     :param folder: 保存的文件夹，fastNLP 将在该文件下以时间戳创建子文件夹，并在里面保存。因此不同次运行可以将被保存到不同的
-        时间戳文件夹中。如果为 None ，默认使用当前文件夹。
-    :param only_state_dict: 保存模型时是否只保存 state_dict 。当 model_save_fn 不为 None 时，该参数无效。
+        时间戳文件夹中。如果为 ``··``None`` ，默认使用当前文件夹。
+    :param only_state_dict: 保存模型时是否只保存 state_dict 。当 ``model_save_fn`` 不为 ``None`` 时，该参数无效。
     :param save_object: 可选 ['trainer', 'model']，表示在保存时的保存对象为 ``trainer+model`` 还是 只是 ``model`` 。如果
-        保存 ``trainer`` 对象的话，将会保存 :class:~fastNLP.Trainer 的相关状态，可以通过 :meth:`Trainer.load_checkpoint` 加载该断
+        保存 ``trainer`` 对象的话，将会保存 :class:`~fastNLP.Trainer` 的相关状态，可以通过 :meth:`Trainer.load_checkpoint` 加载该断
         点继续训练。如果保存的是 ``Model`` 对象，则可以通过 :meth:`Trainer.load_model` 加载该模型权重。
     :param model_save_fn: 个性化的保存函数，当触发保存操作时，就调用这个函数，这个函数应当接受一个文件夹作为参数，不返回任何东西。
-        如果传入了 model_save_fn 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
-    :param save_evaluate_results: 是否保存 evaluate 的结果。如果为 True ，在保存 topk 模型的 folder 中还将额外保存一个
-         ``fastnlp_evaluate_results.json`` 文件，记录当前的 results。仅在设置了 topk 的场景下有用，默认为 True 。
-    :param save_kwargs: dict。更多的保存相关的参数。
-    :param kwargs: 其它与 Evaluator 相关的初始化参数，如果不传入，将从 Trainer 中获取。
+        如果传入了 ``model_save_fn`` 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
+    :param save_evaluate_results: 是否保存 evaluate 的结果。如果为 ``True`` ，在保存 topk 模型的 folder 中还将额外保存一个
+         ``fastnlp_evaluate_results.json`` 文件，记录当前的 results。仅在设置了 ``topk`` 的场景下有效，默认为 True 。
+    :param save_kwargs: 一个字典，表示更多的保存相关的参数。
+    :param kwargs: 其它与 :class:`~fastNLP.Evaluator` 相关的初始化参数，如果不传入，将从 :class:`~fastNLP.Trainer` 中获取。
     """
     def __init__(self, dataloaders, metrics:Dict, evaluate_every:Optional[Union[int, Callable]]=-1,
                  watch_monitor:Union[str, Callable]=None, watch_monitor_larger_better:bool=True,

fastNLP/core/callbacks/progress_callback.py

@@ -60,7 +60,7 @@ def choose_progress_callback(progress_bar: Union[str, ProgressCallback]) -> Prog
 
 class RichCallback(ProgressCallback):
     """
-    在训练过程中打印 rich progress bar 的 callback 。在 Trainer 中，默认就会使用这个 callback 来显示进度。如果需要定制这个 Callback 的
+    在训练过程中打印 *rich* progress bar 的 callback 。在 Trainer 中，默认就会使用这个 callback 来显示进度。如果需要定制这个 Callback 的
     参数，请通过实例化本 Callback 并传入到 Trainer 中实现。在打印 evaluate 的结果时，不会打印名称以 "_" 开头的内容。
 
     :param print_every: 多少个 batch 更新一次显示。
@@ -169,26 +169,26 @@ class RichCallback(ProgressCallback):
 
 
 class RawTextCallback(ProgressCallback):
+    """
+    通过向命令行打印进度的方式显示。在打印 evaluate 的结果时，不会打印名称以 "_" 开头的内容。
+
+    :param print_every: 多少个 batch 更新一次显示。
+    :param loss_round_ndigit: 显示的 loss 保留多少位有效数字
+    :param monitor: 监控的 metric 值。当检测到这个key的结果更好时，会打印出不同的颜色进行提示。
+
+        * 为 ``None``
+            将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
+        * 为 ``str``
+            尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
+            使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
+        * 为 ``Callable``
+            接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
+            的 ``monitor`` 值请返回 ``None`` 。
+    :param larger_better: 是否是monitor的结果越大越好。
+    :param format_json: 是否format json再打印
+    """
     def __init__(self, print_every:int = 1, loss_round_ndigit:int = 6, monitor:str=None, larger_better:bool=True,
                  format_json=True):
-        """
-        通过向命令行打印进度的方式显示。在打印 evaluate 的结果时，不会打印名称以 "_" 开头的内容。
-
-        :param print_every: 多少个 batch 更新一次显示。
-        :param loss_round_ndigit: 显示的 loss 保留多少位有效数字
-        :param monitor: 监控的 metric 值。当检测到这个key的结果更好时，会打印出不同的颜色进行提示。
-
-            * 为 ``None``
-             将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
-            * 为 ``str``
-             尝试直接使用该名称从 ``evaluation`` 结果中寻找，如果在 ``evaluation`` 结果中没有找到完全一致的名称，将
-             使用 最长公共字符串算法 从 ``evaluation`` 结果中找到最匹配的那个作为 ``monitor`` 。
-            * 为 ``Callable``
-             接受参数为 ``evaluation`` 的结果(字典类型)，返回一个 ``float`` 值作为 ``monitor`` 的结果，如果当前结果中没有相关
-             的 ``monitor`` 值请返回 ``None`` 。
-        :param larger_better: 是否是monitor的结果越大越好。
-        :param format_json: 是否format json再打印
-        """
         super().__init__(monitor=monitor, larger_better=larger_better, must_have_monitor=False)
         self.print_every = print_every
         self.task2id = {}
@@ -242,8 +242,9 @@ class RawTextCallback(ProgressCallback):
 
 class TqdmCallback(ProgressCallback):
     """
-    在训练过程中打印 tqdm progress bar 的 callback 。在 Trainer 中，默认就会使用这个 callback 来显示进度。如果需要定制这个 Callback 的
-    参数，请通过实例化本 Callback 并传入到 Trainer 中实现。在打印 evaluate 的结果时，不会打印名称以 "_" 开头的内容。
+    在训练过程中打印 *tqdm* progress bar 的 callback 。在 Trainer 中，如果设置了 ``progress_bar='tqdm'`` 就会使用
+    这个 callback 来显示进度。如果需要定制这个 Callback 的参数，请通过实例化本 Callback 并传入到 Trainer 中实现。在
+    打印 evaluate 的结果时，不会打印名称以 "_" 开头的内容。
 
     :param print_every: 多少个 batch 更新一次显示。
     :param loss_round_ndigit: 显示的 loss 保留多少位有效数字

fastNLP/core/callbacks/timer_callback.py

@@ -68,7 +68,7 @@ class Timers:
 
 class TimerCallback(Callback):
     """
-    这个 callback 的作用是打印训练过程中的相关时间信息，例如训练时长，评测时长，总的时长等
+    这个 callback 的作用是打印训练过程中的相关时间信息，例如训练时长、评测时长、总时长等
 
     """
     def __init__(self, print_every=-1, time_ndigit=3):

fastNLP/core/callbacks/topk_saver.py

@@ -178,8 +178,8 @@ class TopkSaver(ResultsMonitor, Saver):
             - YYYY-mm-dd-HH_MM_SS_fffff/  # 自动根据当前脚本的启动时间创建的
                 - {save_object}-epoch_{epoch_idx}-batch_{global_batch_idx}-{topk_monitor}_{monitor_value}/  # 满足topk条件存储文件名
 
-    :param topk: 保存 topk 多少的模型，-1 为保存所有模型；0 为都不保存；大于 0 的数为保存 topk 个。
-    :param monitor: 监控的 metric 值。
+    :param topk: 保存表现最好的 ``topk`` 个模型，-1 为保存所有模型；0 为都不保存；大于 0 的数为保存 ``topk`` 个；
+    :param monitor: 监控的 metric 值：
 
         * 为 ``None``
          将尝试使用 :class:`~fastNLP.Trainer` 中设置 `monitor` 值（如果有设置）。
@@ -192,14 +192,14 @@ class TopkSaver(ResultsMonitor, Saver):
     :param larger_better: 该 monitor 是否越大越好。
     :param folder: 保存在哪个文件夹下，默认为当前 folder 下。
     :param save_object: 可选 ['trainer', 'model']，表示在保存时的保存对象为 ``trainer+model`` 还是 只是 ``model`` 。如果
-        保存 ``trainer`` 对象的话，将会保存 :class:~fastNLP.Trainer 的相关状态，可以通过 :meth:`Trainer.load_checkpoint` 加载该断
+        保存 ``trainer`` 对象的话，将会保存 :class:`~fastNLP.Trainer` 的相关状态，可以通过 :meth:`Trainer.load_checkpoint` 加载该断
         点继续训练。如果保存的是 ``Model`` 对象，则可以通过 :meth:`Trainer.load_model` 加载该模型权重。
-    :param only_state_dict: 保存时是否仅保存权重，在 model_save_fn 不为 None 时无意义。
+    :param only_state_dict: 保存时是否仅保存权重，在 ``model_save_fn`` 不为 None 时无意义。
     :param model_save_fn: 个性化的保存函数，当触发保存操作时，就调用这个函数，这个函数应当接受一个文件夹作为参数，不返回任何东西。
-        如果传入了 model_save_fn 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
+        如果传入了 ``model_save_fn`` 函数，fastNLP 将不再进行模型相关的保存。在多卡场景下，我们只在 rank 0 上会运行该函数。
     :param save_evaluate_results: 是否保存 evaluate 的结果。如果为 True ，在保存 topk 模型的 folder 中还将额外保存一个
-        ``fastnlp_evaluate_results.json`` 文件，记录当前的 metric results 。仅在设置了 topk 的场景下有用，默认为 True 。
-    :param kwargs: 更多需要传递给 Trainer.save_checkpoint() 或者 Trainer.save_model() 接口的参数。
+        ``fastnlp_evaluate_results.json`` 文件，记录当前的 metric results 。仅在设置了 ``topk`` 的场景下有用，默认为 True 。
+    :param kwargs: 更多需要传递给 :meth:`Trainer.save_checkpoint` 或者 :meth:`Trainer.save_model` 接口的参数。
     """
     def __init__(self, topk:int=0, monitor:str=None, larger_better:bool=True, folder:str=None, save_object:str='model',
                  only_state_dict:bool=True, model_save_fn:Callable=None, save_evaluate_results:bool=True,

fastNLP/core/callbacks/torch_callbacks/torch_grad_clip_callback.py

@@ -11,17 +11,17 @@ if _NEED_IMPORT_FAIRSCALE:
 
 class TorchGradClipCallback(Callback):
     r"""
-    在每次 optimizer update 之前将 parameter 进行 clip 。
+    在每次 :func:`optimizer.step` 之前对参数的梯度进行截断。
 
-    :param clip_value: 将gradient 限制到[-clip_value, clip_value]。clip_value应该为正数
-    :param clip_type: 支持'norm', 'value'两种:
+    :param clip_value: 将梯度限制到 [-clip_value, clip_value] 之间。``clip_value`` 应该为正数；
+    :param clip_type: 应为 ``'norm'``, ``'value'`` 中的一个:
 
-        1. 'norm', 将gradient的norm rescale到[-clip_value, clip_value]
-        2. 'value', 将gradient限制在[-clip_value, clip_value],
-         小于-clip_value的gradient被赋值为-clip_value;大于clip_value的gradient被赋值为clip_value.
+        1. 为 ``'norm'`` 时, 将梯度的范数限制在 [-clip_value, clip_value] 之间；
+        2. 为 ``'value'`` 时，, 将梯度限制在 [-clip_value, clip_value] 之间，小于 ``-clip_value``
+           的梯度被赋值为 ``-clip_value``，大于 ``clip_value`` 的梯度被赋值为 ``clip_value``；
 
-    :param None,torch.Tensor,List[torch.Tensor] parameters: 一般通过model.parameters()获得。
-        如果为None则默认对 Trainer 的 optimizers 中所有参数进行梯度裁剪。
+    :param parameters: 参数，一般通过 :func:`model.parameters` 获得。
+        如果为 ``None`` 则默认对 Trainer 的 optimizers 中所有参数进行梯度裁剪。
     """
     def __init__(self, clip_value:int=1, clip_type:str='norm',
                  parameters:Union["torch.Tensor", List["torch.Tensor"]]=None):

fastNLP/core/callbacks/torch_callbacks/torch_lr_sched_callback.py

@@ -9,14 +9,14 @@ from ..callback import Callback
 
 class TorchWarmupCallback(Callback):
     r"""
-    调整 learning rate 的 callback 。
+    调整学习率的 **callback** 。
 
-    :param warmup: 如果warmup为int，则在该step之前，learning rate根据schedule的策略变化; 如果warmup为float，
-        如0.1, 则前10%的step是按照schedule策略调整learning rate。
-    :param schedule: 以哪种方式调整。
+    :param warmup: 如果 ``warmup`` 为整数，则在该 step 之前，学习率根据 ``schedule`` 的策略变化; 如果 ``warmup`` 为 ``float``，
+        如 0.1, 则前 10% 的 step 是按照 ``schedule`` 策略调整。
+    :param schedule: 对学习率进行调整的策略：
 
-        1. linear: 前warmup的step上升到指定的learning rate(从Trainer中的optimizer处获取的), 后warmup的step下降到0；
-        2. constant前warmup的step上升到指定learning rate，后面的step保持learning rate.
+        1. *linear* -- 前 ``warmup`` 的 step 上升到指定的学习率（从 Trainer 中 optimizer 处获取）, 在剩下的 step 中下降到 0；
+        2. *constant* -- 前 ``warmup`` 的 step 上升到指定的学习率，余下的 step 保持不变。
     """
     def __init__(self, warmup:Union[int, float]=0.1, schedule:str='constant'):
         super().__init__()