【完善】补全代码实现格式整理

docs/code-completion/_thread.py

@@ -1,5 +1,6 @@
 """
-_thread 模块提供了用于处理多线程的基本方法——多个控制线程共享它们的全局数据空间。为了实现同步，提供了简单的锁（也称为互斥锁或二进制信号量）。
+_thread 模块提供了用于处理多线程的基本方法——多个控制线程共享它们的全局数据空间。
+为了实现同步，提供了简单的锁（也称为互斥锁或二进制信号量）。
 """
 
 def start_new_thread(testThread) -> None:

docs/code-completion/array.py

@@ -4,7 +4,8 @@ array 模块定义了一个对象类型，它可以简洁地表示基本值的
 
 class array(object):
     def __init__(self) -> None:
-    """用给定类型的元素创建数组。数组的初始内容由 iterable 提供，如果没有提供，则创建一个空数组。
+    """
+    用给定类型的元素创建数组。数组的初始内容由 iterable 提供，如果没有提供，则创建一个空数组。
     typecode：数组的类型
     iterable：数组初始内容
     示例：
@@ -20,7 +21,8 @@ class array(object):
     ...
 
     def append(val) -> None:
-        """将一个新元素追加到数组的末尾。
+        """
+        将一个新元素追加到数组的末尾。
         示例：
 
         - a = array.array('f', [3, 6])
@@ -33,7 +35,8 @@ class array(object):
         ...
 
     def extend(iterable) -> None:
-        """将一个新的数组追加到数组的末尾，注意追加的数组和原来数组的数据类型要保持一致。
+        """
+        将一个新的数组追加到数组的末尾，注意追加的数组和原来数组的数据类型要保持一致。
         示例：
 
         - a = array.array('i', [1, 2, 3])

docs/code-completion/math.py

@@ -202,14 +202,17 @@ def sinh(x) -> None:
     ...
 
 def sqrt(x) -> None:
-    """计算平方根。 示例：
+    """
+    计算平方根。 
+    示例：
     - x = math.sqrt(9)
     - print(x)
     3.0"""
     ...
 
 def tan(x) -> None:
-    """传入弧度值，计算正切。 示例：计算tan60°
+    """
+    传入弧度值，计算正切。 示例：计算tan60°
     - math.tan(math.radians(60))
     1.732051"""
     ...
@@ -219,7 +222,9 @@ def tanh(x) -> None:
     ...
 
 def trunc(x) -> None:
-    """取整。 示例：
+    """
+    取整。 
+    示例：
     - x = math.trunc(5.12)
     - print(x)
     5

docs/code-completion/network.py

@@ -7,7 +7,10 @@ AP_IF = ...  # type: int
 
 class WLAN(object):
     """
-    创建一个 WLAN 网络接口对象。支持的接口是 network.STA_IF（STA 模式，可以连接到上游的 WiFi 热点上） 和 network.AP_IF（AP 模式，允许其他 WiFi 客户端连接到自身的热点)。下面方法的可用性取决于接口的类型。例如，只有STA 接口可以使用 WLAN.connect()  方法连接到 AP 热点上。
+    创建一个 WLAN 网络接口对象。
+    支持的接口是 network.STA_IF（STA 模式，可以连接到上游的 WiFi 热点上） 和 network.AP_IF（AP 模式，允许其他 WiFi 客户端连接到自身的热点)。
+    下面方法的可用性取决于接口的类型。
+    例如，只有STA 接口可以使用 WLAN.connect() 方法连接到 AP 热点上。
     """
 
     STAT_IDLE = ...  # type: int

docs/code-completion/select.py

@@ -3,7 +3,8 @@ uselect 模块提供了等待数据流的事件功能。
 """
 
 def select(rlist, wlist, xlist) -> None:
-    """监控对象何时可读或可写，一旦监控的对象状态改变，返回结果（阻塞线程）。这个函数是为了兼容，效率不高，推荐用 poll 函数 。
+    """
+    监控对象何时可读或可写，一旦监控的对象状态改变，返回结果（阻塞线程）。这个函数是为了兼容，效率不高，推荐用 poll 函数 。
 
     - select.select(rlist, wlist, xlist[, timeout])
 
@@ -27,7 +28,8 @@ def select(rlist, wlist, xlist) -> None:
     ...
 
 class poll(string):
-    """创建 poll 实例。
+    """
+    创建 poll 实例。
 
     示例：
 
@@ -53,9 +55,11 @@ class poll(string):
         ...
 
     def unregister(obj) -> None:
-        """解除监控的对象的注册。
+        """
+        解除监控的对象的注册。
+
+        - obj：注册过的对象
 
-        obj：注册过的对象
         示例：
 
         - READ_ONLY = select.POLLIN | select.POLLHUP | select.POLLERR
@@ -66,7 +70,8 @@ class poll(string):
         ...
 
     def modify(obj, eventmask) -> None:
-        """修改已注册的对象监控标志。
+        """
+        修改已注册的对象监控标志。
 
         - obj：已注册的被监控对象
         - flag：修改为的监控标志
@@ -83,7 +88,9 @@ class poll(string):
     def poll(timeout) -> None:
         """
         - poll([timeout])
-        等待至少一个已注册的对象准备就绪。返回 (obj, event, ...) 元组, event 元素指定了一个流发生的事件，是上面所描述的 select.POLL*常量组合。 根据平台和版本的不同，在元组中可能有其他元素，所以不要假定元组的大小是 2 。如果超时，则返回空列表。
+        等待至少一个已注册的对象准备就绪。
+        返回 (obj, event, ...) 元组, event 元素指定了一个流发生的事件，是上面所描述的 select.POLL*常量组合。 
+        根据平台和版本的不同，在元组中可能有其他元素，所以不要假定元组的大小是 2 。如果超时，则返回空列表。
         """
         ...
 

docs/code-completion/ubinascii.py

@@ -26,7 +26,8 @@ def hexlify(data]) -> None:
     ...
 
 def unhexlify(data) -> None:
-    """转换十六进制字符串为二进制字符串，功能和 hexlify 相反。
+    """
+    转换十六进制字符串为二进制字符串，功能和 hexlify 相反。
 
     示例：
 

docs/code-completion/ucollections.py

@@ -3,7 +3,8 @@ ucollections 模块实现了专门的容器数据类型，它提供了 Python
 """
 
 class namedtuple(name, fields):
-    """这是工厂函数创建一个新的 namedtuple 型与一个特定的字段名称和集合。namedtuple 是元组允许子类要访问它的字段不仅是数字索引，而且还具有属性使用符号字段名访问语法。 字段是字符串序列指定字段名称。为了兼容的实现也可以用空间分隔的字符串命名的字段（但效率较低） 。
+    """
+    这是工厂函数创建一个新的 namedtuple 型与一个特定的字段名称和集合。namedtuple 是元组允许子类要访问它的字段不仅是数字索引，而且还具有属性使用符号字段名访问语法。 字段是字符串序列指定字段名称。为了兼容的实现也可以用空间分隔的字符串命名的字段（但效率较低） 。
     代码示例：
 
     - from ucollections import namedtuple
@@ -17,7 +18,8 @@ class namedtuple(name, fields):
     ...
 
 class OrderedDict(...):
-    """字典类型的子类，会记住并保留键/值的追加顺序。当有序的字典被迭代输出时，键/值 会按照他们被添加的顺序返回 :
+    """
+    字典类型的子类，会记住并保留键/值的追加顺序。当有序的字典被迭代输出时，键/值 会按照他们被添加的顺序返回 :
     from ucollections import OrderedDict
 
     # To make benefit of ordered keys, OrderedDict should be initialized

docs/code-completion/uctypes.py

@@ -7,7 +7,8 @@ BIG_ENDIAN  = ...  # type: int
 NATIVE  = ...  # type: int
 
 class struct(addr, descriptor, type):
-    """将内存中以 c 形式打包的结构体或联合体转换为字典，并返回该字典。
+    """
+    将内存中以 c 形式打包的结构体或联合体转换为字典，并返回该字典。
 
     - addr：开始转换的地址
     - descriptor：转换描述符
@@ -44,7 +45,8 @@ class struct(addr, descriptor, type):
         ...
 
     def addressof(obj) -> None:
-        """返回对象地址。参数需要是 bytes, bytearray 。 示例：
+        """
+        返回对象地址。参数需要是 bytes, bytearray 。 示例：
 
         - a = b"0123"
         - print(uctypes.addressof(a))
@@ -53,7 +55,8 @@ class struct(addr, descriptor, type):
         ...
 
     def bytes_at(addr, size)-> None:
-        """捕捉从 addr 开始到 size 个地址偏移量结束的内存数据为 bytearray 对象并返回。 示例：
+        """
+        捕捉从 addr 开始到 size 个地址偏移量结束的内存数据为 bytearray 对象并返回。 示例：
 
         - a = b"0123"
         - print( uctypes.bytes_at(uctypes.addressof(a), 4))

docs/code-completion/uio.py

@@ -19,7 +19,10 @@ class StringIO(string):
     ...
 
 class BytesIO(string):
-    """内存文件对象。StringIO 用于文本模式 I/O (用 “t” 打开文件)，BytesIO 用于二进制方式 (用 “b” 方式)。文件对象的初始内容可以用字符串参数指定（stringio用普通字符串，bytesio用bytes对象）。所有的文件方法，如 read(), write(), seek(), flush(), close() 都可以用在这些对象上。
+    """
+    内存文件对象。StringIO 用于文本模式 I/O (用 “t” 打开文件)，BytesIO 用于二进制方式 (用 “b” 方式)。
+    文件对象的初始内容可以用字符串参数指定（stringio用普通字符串，bytesio用bytes对象）。
+    所有的文件方法，如 read(), write(), seek(), flush(), close() 都可以用在这些对象上。
     """
     def __init__(self) -> None:
     ...

docs/code-completion/ujson.py

@@ -3,7 +3,8 @@ ujson 模块提供 Python 对象到 JSON（JavaScript Object Notation） 数据
 """
 
 def dumps(obj) -> None:
-    """将 dict 类型转换成 str。
+    """
+    将 dict 类型转换成 str。
 
     - obj：要转换的对象
 
@@ -18,7 +19,10 @@ def dumps(obj) -> None:
     ...
 
 def loads(str) -> None:
-    """解析 JSON 字符串并返回对象。如果字符串格式错误将引发 ValueError 异常。 示例：
+    """
+    解析 JSON 字符串并返回对象。如果字符串格式错误将引发 ValueError 异常。 
+    
+    示例：
 
     - obj = {1:2, 3:4, "a":6}
     - jsDumps = json.dumps(obj)

docs/code-completion/urandom.py

@@ -93,7 +93,10 @@ def randrange(start, end, step) -> None:
 
 def seed(sed) -> None:
     """
-    指定随机数种子，通常和其他随机数生成函数搭配使用。 注意： MicroPython 中的随机数其实是一个稳定算法得出的稳定结果序列，而不是一个随机序列。sed 就是这个算法开始计算的第一个值。所以就会出现只要 sed 是一样的，那么后续所有“随机”结果和顺序也都完全一致。
+    指定随机数种子，通常和其他随机数生成函数搭配使用。 
+    注意： MicroPython 中的随机数其实是一个稳定算法得出的稳定结果序列，而不是一个随机序列。
+    sed 就是这个算法开始计算的第一个值。
+    所以就会出现只要 sed 是一样的，那么后续所有“随机”结果和顺序也都完全一致。
     """
     ...
 

docs/code-completion/uscoket.py

@@ -142,14 +142,21 @@ class socket(family, type, protocol) -> None:
     def read(size) -> None:
         """
         - read([size])
-        Read up to size bytes from the socket. Return a bytes object. If size is not given, it reads all data available from the socket until EOF; as such the method will not return until the socket is closed. This function tries to read as much data as requested (no “short reads”). This may be not possible with non-blocking socket though, and then less data will be returned.
+        Read up to size bytes from the socket. 
+        Return a bytes object. If size is not given, it reads all data available from the socket until EOF; 
+        as such the method will not return until the socket is closed. This function tries to read as much data as requested (no “short reads”). 
+        This may be not possible with non-blocking socket though, and then less data will be returned.
         """
         ...
 
     def readinto(buf) -> None:
         """
         readinto(buf[, nbytes])
-        Read bytes into the buf. If nbytes is specified then read at most that many bytes. Otherwise, read at most len(buf) bytes. Just as read(), this method follows “no short reads” policy. Return value: number of bytes read and stored into buf.
+        Read bytes into the buf. 
+        If nbytes is specified then read at most that many bytes. 
+        Otherwise, read at most len(buf) bytes. 
+        Just as read(), this method follows “no short reads” policy. 
+        Return value: number of bytes read and stored into buf.
         """
         ...
         

docs/code-completion/ustruct.py

@@ -6,7 +6,8 @@ ustruct 模块在 Python 值和以 Python 字节对象表示的 C 结构之间
 """
 
 def calcsize(fmt) -> None:
-    """返回存放某一类型数据 fmt 需要的字节数。
+    """
+    返回存放某一类型数据 fmt 需要的字节数。
     - fmt：数据类型
     -     b — 字节型
     -     B — 无符号字节型
@@ -31,7 +32,8 @@ def calcsize(fmt) -> None:
     ...
 
 def pack(fmt, v1, v2, ...) -> None:
-    """按照格式字符串 fmt 打包参数 v1, v2, ... 。返回值是参数打包后的字节对象。
+    """
+    按照格式字符串 fmt 打包参数 v1, v2, ... 。返回值是参数打包后的字节对象。
     fmt：同 calcsize。
     示例：
 
@@ -55,7 +57,9 @@ def pack_into(fmt, buffer, offset, v1, v2, ...) -> None:
     ...
 
 def unpack_from(fmt, data, offset=0) -> None:
-    """以 fmt 作为规则从 data 的 offset 位置开始解包数据，如果 offset 是负数就是从缓冲区末尾开始计算。返回值是解包后的参数元组。
+    """
+    以 fmt 作为规则从 data 的 offset 位置开始解包数据，如果 offset 是负数就是从缓冲区末尾开始计算。
+    返回值是解包后的参数元组。
     - buf = struct.pack("bb", 1, 2)
     - print(struct.unpack("bb", buf))
     - (1, 2)

docs/code-completion/utime.py

@@ -34,13 +34,21 @@ def sleep_us(us) -> None:
     ...
 
 def ticks_ms() -> None:
-    """返回不断递增的毫秒计数器，在某些值后会重新计数(未指定)。计数值本身无特定意义，只适合用在ticks_diff()。
-    注： 直接在这些值上执行标准数学运算（+，-）或关系运算符（<，>，>，> =）会导致无效结果。执行数学运算然后传递结果作为参数给ticks_diff() 或 ticks_add() 也将导致函数产生无效结果。"""
+    """
+    返回不断递增的毫秒计数器，在某些值后会重新计数(未指定)。
+    计数值本身无特定意义，只适合用在ticks_diff()。
+    注： 直接在这些值上执行标准数学运算（+，-）或关系运算符（<，>，>，> =）会导致无效结果。
+    执行数学运算然后传递结果作为参数给ticks_diff() 或 ticks_add() 也将导致函数产生无效结果。
+    """
     ...
 
 def ticks_us() -> None:
-    """返回不断递增的微秒计数器，在某些值后会重新计数(未指定)。计数值本身无特定意义，只适合用在ticks_diff()。
-    注： 直接在这些值上执行标准数学运算（+，-）或关系运算符（<，>，>，> =）会导致无效结果。执行数学运算然后传递结果作为参数给ticks_diff() 或 ticks_add() 也将导致函数产生无效结果。"""
+    """
+    返回不断递增的微秒计数器，在某些值后会重新计数(未指定)。
+    计数值本身无特定意义，只适合用在ticks_diff()。
+    注： 直接在这些值上执行标准数学运算（+，-）或关系运算符（<，>，>，> =）会导致无效结果。
+    执行数学运算然后传递结果作为参数给ticks_diff() 或 ticks_add() 也将导致函数产生无效结果。
+    """
     ...
 
 def ticks_cpu() -> None:
@@ -48,11 +56,22 @@ def ticks_cpu() -> None:
     ...
 
 def ticks_add(ticks, delta) -> None:
-    """给定一个数字作为节拍的偏移值 delta，这个数字的值是正数或者负数都可以。 给定一个 ticks 节拍值，本函数允许根据节拍值的模算数定义来计算给定节拍值之前或者之后 delta 个节拍的节拍值 。 ticks 参数必须是 ticks_ms(), ticks_us(), or ticks_cpu() 函数的直接返回值。然而，delta 可以是一个任意整数或者是数字表达式。ticks_add 函数对计算事件/任务的截至时间很有用。（注意：必须使用 ticksdiff() 函数来处理 最后期限)。"""
+    """
+    给定一个数字作为节拍的偏移值 delta，这个数字的值是正数或者负数都可以。 
+    给定一个 ticks 节拍值，本函数允许根据节拍值的模算数定义来计算给定节拍值之前或者之后 delta 个节拍的节拍值 。 
+    ticks 参数必须是 ticks_ms(), ticks_us(), or ticks_cpu() 函数的直接返回值。
+    然而，delta 可以是一个任意整数或者是数字表达式。ticks_add 函数对计算事件/任务的截至时间很有用。
+    （注意：必须使用 ticksdiff() 函数来处理 最后期限)。
+    """
     ...
 
 def ticks_diff(ticks1, ticks2) -> None:
-    """计算两次调用 ticksms(), ticks_us(), 或 ticks_cpu()之间的时间。因为这些函数的计数值可能会回绕，所以不能直接相减，需要使用 ticks_diff() 函数。“旧” 时间需要在 “新” 时间之前，否则结果无法确定。这个函数不要用在计算很长的时间 (因为 ticks*() 函数会回绕，通常周期不是很长)。通常用法是在带超时的轮询事件中调用:
+    """
+    计算两次调用 ticksms(), ticks_us(), 或 ticks_cpu()之间的时间。
+    因为这些函数的计数值可能会回绕，所以不能直接相减，需要使用 ticks_diff() 函数。
+    “旧” 时间需要在 “新” 时间之前，否则结果无法确定。
+    这个函数不要用在计算很长的时间 (因为 ticks*() 函数会回绕，通常周期不是很长)。
+    通常用法是在带超时的轮询事件中调用:
     代码示例：
     # 等待 GPIO 引脚有效，但是最多等待500微秒
 
@@ -64,5 +83,10 @@ def ticks_diff(ticks1, ticks2) -> None:
     ...
 
 def time() -> None:
-    """返回从开始时间的秒数（整数），假设 RTC 已经按照前面方法设置好。如果 RTC 没有设置，函数将返回参考点开始计算的秒数 (对于 RTC 没有后备电池的板子，上电或复位后的情况)。如果你开发便携版的 MicroPython 应用程序，你不要依赖函数来提供超过秒级的精度。如果需要高精度，使用 ticks_ms() 和 ticks_us() 函数。如果需要日历时间，使用不带参数的 localtime() 是更好选择。"""
+    """
+    返回从开始时间的秒数（整数），假设 RTC 已经按照前面方法设置好。
+    如果 RTC 没有设置，函数将返回参考点开始计算的秒数 (对于 RTC 没有后备电池的板子，上电或复位后的情况)。
+    如果你开发便携版的 MicroPython 应用程序，你不要依赖函数来提供超过秒级的精度。
+    如果需要高精度，使用 ticks_ms() 和 ticks_us() 函数。
+    如果需要日历时间，使用不带参数的 localtime() 是更好选择。"""
     ...