```python

```python """ 这是一个示例 Python 模块。

这个模块包含一些简单的函数，演示了 Python 代码的文档化方式。 """

def greet(name): """ 这个函数用于打招呼。

:param name: 要打招呼的人的名字。 :type name: str :raises TypeError: 如果 name 不是字符串类型。 :returns: 打招呼的信息。 :rtype: str """ if not isinstance(name, str): raise TypeError("name 必须是字符串类型") return f"你好，{name}！"

def add(x, y): """ 这个函数用于将两个数字相加。

:param x: 第一个数字。 :type x: int or float :param y: 第二个数字。 :type y: int or float :returns: 两个数字的和。 :rtype: int or float """ return x + y ```

解释

这个 Python 文档以 markdown 格式编写，包含以下部分：

• 模块级文档字符串: 位于模块开头，使用三个双引号包围。它描述了模块的总体功能和目的。
• 函数级文档字符串: 位于每个函数定义的下方，同样使用三个双引号包围。它描述了函数的功能、参数、返回值、异常信息和类型。
• 参数说明: 使用 :param name: 说明 形式，描述参数的名称和用途。
• 类型说明: 使用 :type name: 类型 形式，描述参数和返回值的类型。
• 异常说明: 使用 :raises 异常类型: 说明 形式，描述函数可能会抛出的异常类型。
• 返回值说明: 使用 :returns: 说明 形式，描述函数的返回值。
• 返回值类型说明: 使用 :rtype: 类型 形式，描述返回值的类型。

使用

这个文档可以使用 pydoc 工具进行查看，例如：

pydoc 模块名

或者使用 help 函数：

python help(模块名.函数名)

总结

这是一个简单的 Python 文档示例，展示了如何使用 markdown 格式编写代码文档，并使用文档字符串和说明来增强代码的可读性和可维护性。