doc: update doc

docs/guide.rst

@@ -405,10 +405,12 @@ PyWebIO 支持在多线程环境中使用。
 
 **Server mode**
 
-Server mode 下，如果需要在新创建的线程中使用PyWebIO的交互函数，需要手动调用 `register_thread(thread) <pywebio.session.register_thread>` 对新进程进行注册(这样PyWebIO才能知道新创建的线程属于那个会话)。
+Server mode 下，如果需要在新创建的线程中使用PyWebIO的交互函数，需要手动调用 `register_thread(thread) <pywebio.session.register_thread>` 对新进程进行注册（这样PyWebIO才能知道新创建的线程属于哪个会话）。
 如果新创建的线程中没有使用到PyWebIO的交互函数，则无需注册。在没有使用 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程不受会话管理，其调用PyWebIO的交互函数将会产生 `SessionNotFoundException <pywebio.exceptions.SessionNotFoundException>` 异常。
 当会话的任务函数和会话内通过 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程都结束运行时，会话关闭。
 
+.. _session_close:
+
 会话的结束
 ^^^^^^^^^^^^^^
 
@@ -427,6 +429,9 @@ PyWebIO 目前支持与Flask、Tornado、Django和aiohttp Web框架的集成。
 与Web框架集成需要完成两件工作：托管PyWebIO静态文件；暴露PyWebIO后端接口。
 这其中需要注意前端页面和后端接口的路径约定，以及前端静态文件与后端接口分开部署时因为跨域而需要的特别设置。
 
+集成方法
+^^^^^^^^^^^
+
 不同Web框架的集成方法如下：
 
 .. tabs::
@@ -579,12 +584,14 @@ PyWebIO默认通过当前页面的同级的 ``./io`` API与后端进行通讯。
 ---------------
 此部分内容属于高级特性，您不必使用此部分也可以实现PyWebIO支持的全部功能。PyWebIO中所有仅用于协程会话的函数或方法都在文档中有特别说明。
 
-PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务端的会话连接，PyWebIO会启动一个线程来运行任务函数，你可以在会话中启动新的线程，通过 `register_thread(thread) <pywebio.session.register_thread>` 注册新创建的线程后新线程中也可以调用PyWebIO交互函数，当任务函数返回并且会话内所有的通过 `register_thread(thread) <pywebio.session.register_thread>` 注册的线程都退出后，会话结束。
-
+PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务端的会话连接，PyWebIO会启动一个线程来运行任务函数。
 除了基于线程的会话，PyWebIO还提供了基于协程的会话。基于协程的会话接受一个协程作为任务函数。
 
 基于线程的会话为单线程模型，所有会话都运行在一个线程内。对于IO密集型的任务，协程比线程有更少的资源占用同时又拥有媲美于线程的性能。
 
+使用协程会话
+^^^^^^^^^^^^^^^^
+
 要使用基于协程的会话，需要使用 ``async`` 关键字将任务函数声明为协程函数，并使用 ``await`` 语法调用PyWebIO输入函数:
 
 .. code-block:: python
@@ -662,8 +669,13 @@ PyWebIO的会话实现默认是基于线程的，用户每打开一个和服务
     start_server(main, auto_open_webbrowser=True)
 
 `run_async(coro) <pywebio.session.run_async>` 返回一个 `TaskHandle <pywebio.session.coroutinebased.TaskHandle>` ，通过 ``TaskHandle`` 你可以查询协程运行状态和关闭协程。
+
+协程会话的关闭
+^^^^^^^^^^^^^^^^
 与基于线程的会话类似，在基于协程的会话中，当任务函数和在会话内通过 ``run_async()`` 运行的协程全部结束后，会话关闭。
 
+对于因为用户的关闭浏览器而造成的会话结束，处理逻辑和 :ref:`基于线程的会话 <session_close>` 一致。协程会话也同样支持使用 `defer_call(func) <pywebio.session.defer_call>` 来设置会话结束时需要调用的函数。
+
 协程会话与Web框架集成
 ^^^^^^^^^^^^^^^^^^^^^^^^^
 

pywebio/input.py

@@ -21,7 +21,7 @@
    PyWebIO 根据是否在输入函数中传入 ``name`` 参数来判断输入函数是在 `input_group` 中还是被单独调用。
    所以当你想要单独调用一个输入函数时，请不要设置 ``name`` 参数；而在 `input_group` 中调用输入函数时，**务必提供** ``name`` 参数
 
-输入默认可以忽略，如果需要用户必须提供值，则需要在输入函数中传入 ``required=True`` ( ``checkbox()` 和 `acrions()` 不支持 ``required`` 参数)
+输入默认可以忽略，如果需要用户必须提供值，则需要在输入函数中传入 ``required=True`` (部分输入函数不支持 ``required`` 参数)
 """
 
 import logging
@@ -344,13 +344,15 @@ def actions(label='', buttons=None, name=None, help_text=None):
     :return: 若用户点击点击 ``type=submit`` 按钮进行表单提交，返回用户点击的按钮的值；若用户点击点击 ``type=callback`` 按钮，返回值通过回调函数设置；
        若用户点击 ``type=cancel`` 按钮或通过其它方式提交表单，则返回 ``None``
 
-    ** ``type=callback`` 时的用法 **
+    **type=callback的用法**
 
-    回调函数需要接收一个 ``set_value`` 位置参数， ``set_value`` 是一个可调用对象，签名为 ``set_value(value, label)`` ，其中 ``label`` 参数可选，
-    调用 ``set_value`` 将会设置 actions 输入项的值，``value`` 参数可以为任意PytHon对象， ``value`` 参数并不会传递给用户浏览器，用户表单上仅会显示 ``label`` 参数，
-    默认 ``label`` 为 ``value`` 的字符串表示。
+    回调函数需要接收一个 ``set_value`` 位置参数， ``set_value`` 是一个可调用对象，调用 ``set_value`` 将会设置 actions 输入项的值，
+    调用签名为 ``set_value(value:any, label:str)`` ，其中
 
-    示例代码见下方"处理复杂输入"的场景。
+    * ``value`` 参数为最终 actions 输入项的返回值，可以为任意Python对象，并不会传递给用户浏览器
+    * ``label`` 参数可选，用于显示在用户表单上， ``label`` 默认为 ``value`` 的字符串表示
+
+    示例代码见下方"通过其他操作设置项值"使用场景。
 
     Note: 当使用 :ref:`基于协程的会话实现 <coroutine_based_session>` 时，回调函数可以使用协程函数.
 

pywebio/output.py

@@ -489,9 +489,9 @@ def put_buttons(buttons, onclick, small=None, link_style=False, scope=Scope.Curr
            * mutex_mode: 互斥模式。默认为 ``False`` 。若为 ``True`` ，则在运行回调函数过程中，无法响应当前按钮组的新点击事件，仅当 ``onclick`` 为协程函数时有效
 
        ThreadBasedSession 实现
-           * serial_mode: 串行模式模式。默认为 ``False`` 。若为 ``True`` ，则运行当前点击事件时，其他所有新的点击事件都将被排队等待当前点击事件时运行完成。
-             不开启 ``serial_mode`` 时，ThreadBasedSession 在新线程中执行回调函数。所以如果回调函数运行时间很短，
-             可以关闭 ``serial_mode`` 来提高性能。
+           * serial_mode: 串行模式模式。默认为 ``False`` ，此时每次触发回调，回调函数会在新线程中立即执行。
+           对于开启了serial_mode的回调，都会在会话内的一个固定线程内执行，当会话运行此回调时，其他所有新的点击事件的回调(包括 ``serial_mode=False`` 的回调)都将排队等待当前点击事件运行完成。
+           如果回调函数运行时间很短，可以开启 ``serial_mode`` 来提高性能。
 
     使用示例::
 

pywebio/platform/httpbased.py

@@ -158,6 +158,7 @@ class HttpHandler:
 
         request_headers = context.request_headers()
 
+        # CORS process start ############################
         if context.request_method() == 'OPTIONS':  # preflight request for CORS
             self._process_cors(context)
             context.set_status(204)
@@ -169,6 +170,7 @@ class HttpHandler:
         if context.request_url_parameter('test'):  # 测试接口，当会话使用给予http的backend时，返回 ok
             context.set_content('ok')
             return context.get_response()
+        # CORS process end ############################
 
         webio_session_id = None
 

pywebio/session/threadbased.py

@@ -15,7 +15,7 @@ logger = logging.getLogger(__name__)
 """
 基于线程的会话实现
 
-主任务线程退出后，连接关闭。
+当任务函数返回并且会话内所有的通过 register_thread(thread) 注册的线程都退出后，会话结束，连接关闭。
 正在等待PyWebIO输入的线程会在输入函数中抛出SessionClosedException异常，
 其他线程若调用PyWebIO输入输出函数会引发异常SessionException
 """