19、Python 代码文档化：从基础到高级工具

Python 代码文档化：从基础到高级工具

1. 代码关系与示例的重要性

在代码编写过程中，有两种重要的关系需要进行文档记录。首先是依赖关系，一个部分可能在逻辑上（通过继承或组合）、功能上（例如通过导入）或时间上（可能一个部分为另一个部分的正确运行执行设置）依赖于另一个部分，所有这些依赖关系都应该被记录下来。其次是属于同一模式的关系，如果一个类是某个设计模式实现的一部分，也应该进行文档记录。

示例在文档中也有着不可替代的作用，有时候示例就是最有用的文档形式。下面以中国剩余定理的 Python 实现为例进行说明：

"""Company boilerplate goes here.
Suppose n1, ..., nk are positive integers that are pairwise coprime. Then, for any 
given sequence of integers a1, ..., ak, there exists an integer x solving the following 
system of simultaneous congruences.
x ≡ a1 mod n1
x ≡ a2 mod n2
…
x ≡ ak mod nk
A full explanation of the theorem can be found at https://en.wikipedia.org/
wiki/Chinese_remainder_theorem.
Attributes:
    None
Dependencies:
    functools
"""
import functoo