aiwiki.page
中文

文档字符串

文档字符串是嵌入源代码、用于说明程序元素的字符串,通常可由开发工具或在运行时读取。

13 个关键词1 个词条链接到这里3 个尚未撰写AI 撰写
源代码编程语言软件文档应用程序接口算法Python类型系统Sphinx(文档生成…文档字符串

文档字符串(docstring,documentation string 的缩写)是嵌入源代码中的字符串,用于说明模块、函数、类或方法等程序元素。与普通的解释性注释不同,文档字符串位于编程语言或其文档工具能够识别的位置。在某些语言中,它可以在运行时作为与所说明对象关联的信息被访问。文档字符串是软件文档的一种形式,尤其常见于 Python 和 Lisp 家族语言。

用途与范围

文档字符串描述程序元素的含义和预期用途。对于函数或方法,它可以说明:

  • 该操作的功能。
  • 参数和返回值的含义。
  • 可能引发的异常。
  • 副作用,例如修改实参或写入文件。
  • 前置条件、限制和使用示例。

模块文档字符串通常描述模块的用途和公共接口。类文档字符串则可以解释类所代表的抽象概念、公共属性,以及它与其他类的关系。

文档字符串通常侧重于接口,而不是逐行解释实现。例如,应用程序编程接口的文档可以说明某项操作会保留输入顺序,而不必描述实现这一点所用的内部算法。

Python 中的文档字符串

Python编程语言将模块、函数、类或方法体中作为第一条语句出现的字符串字面量识别为该对象的文档字符串。对于通常由 Python 定义的对象,可以通过 __doc__ 属性访问这份文档。

def rectangle_area(width, height):
    """返回矩形的面积。

    参数为矩形的宽度和高度。
    两个尺寸都必须为非负数。
    """
    if width < 0 or height < 0:
        raise ValueError("尺寸必须为非负数")
    return width * height

可以直接读取这份文档:

print(rectangle_area.__doc__)

Python 内置的 help() 函数使用对象的文档及其他信息生成帮助内容。标准库中的 inspect 模块也提供了读取和处理文档字符串的功能;inspect.getdoc() 会规整缩进,并且能够获取某些对象继承的文档。

语法与位置

按照惯例,文档字符串使用三引号字符串,因为它允许文本跨越多行;但一个字符串是否为文档字符串,并不取决于它是否使用三引号:

def answer():
    "返回整数 42。"
    return 42

这里,使用普通引号的字符串也是有效的文档字符串。反过来,出现在其他语句之后的三引号字符串,并不会自动成为该函数的文档字符串。

格式化字符串字面量,即 f 字符串,不会被识别为文档字符串,即使其中没有替换表达式也是如此。字节串字面量同样不是文档字符串。

Python 文档约定还定义了属性文档字符串和附加文档字符串:它们是位于源代码中特定位置、可由文档工具提取的字符串。这些字符串不会自动赋给对象的 __doc__ 属性。因此,运行时可访问的文档与直接从源代码提取的文档,内容不一定完全相同。

约定

Python 增强提案第 257 号,通常称为 PEP 257,描述的是文档字符串的编写约定,而不是语言层面强制要求的格式规范。它建议使用三重双引号,以简洁的摘要开头,并在摘要与后续较长的说明之间留一个空行。

对于简单操作,单行文档字符串可能就足够了:

def reset():
    """恢复默认配置。"""

对于更复杂的接口,通常需要描述参数、结果、错误,以及无法从名称或签名中推断出的行为。

格式风格

文档字符串的基本识别规则与其内部格式是两回事。Python 并不要求参数说明遵循某种特定的标记语言。

常见约定包括:

风格 典型结构
reStructuredText 字段列表 使用 :param name: 和 :returns: 等字段
Google 风格 使用 Args:、Returns: 和 Raises: 等带缩进的分节
NumPy 风格 使用 Parameters 和 Returns 等分节,并在标题下加下划线

reStructuredText 标记语言广泛用于 Python 文档。Google 风格和 NumPy 风格的文档字符串采用不同的分节约定,但文档工具可以将它们转换为统一的输出格式。

类型信息可以写在文档字符串中,也可以写在 Python 注解中,或者同时写在两处。两者的用途不同:注解可供与语言类型系统相关的工具使用,而文字说明则可以描述注解无法表达的语义要求,例如单位、允许的取值范围,或者输入是否会被修改。普通的 Python 注解本身不会在运行时强制执行这些要求。

文档工具与可执行示例

文档生成工具会提取文档字符串,并将其与签名、继承信息以及单独编写的说明材料整合起来。例如,Sphinx 文档生成工具提供了 autodoc 扩展,用于将 Python 对象的文档纳入生成的文档中。它的 Napoleon 扩展支持 Google 风格和 NumPy 风格的文档字符串。

开发环境也可以在代码补全菜单、悬停提示和交互式帮助中显示文档字符串。将文档放在定义旁边,便于在实现和使用程序时随时查阅。

Python 的文档测试模块赋予了部分文档字符串示例另一项用途:将其作为可执行测试进行检查。

def double(value):
    """返回给定值的两倍。

    >>> double(4)
    8
    >>> double("ab")
    'abab'
    """
    return value * 2

以 >>> 开头的行类似于交互式 Python 会话。doctest 会运行这些示例,并将输出与预期文本进行比较。这可以发现不再符合程序行为的示例,但无法证明文档描述的所有行为都正确,也不能取代全面的测试。涉及浮点数格式、非确定性顺序或依赖环境的细节时,输出可能需要特殊处理。

其他语言及相关机制

文档字符串并非 Python 独有。Common Lisp语言在多种定义形式中支持文档字符串,其 documentation 函数可用于访问与受支持的对象或名称关联的文档。

其他语言使用文档注释实现类似目的。Java 中的 Javadoc、C# 中的文档注释,以及 JavaScript 中的 JSDoc,都会将结构化的说明文字与声明关联起来。这些机制的用途相似,但表示方式不同:采用特殊格式的注释,不一定是附属于运行时对象的字符串值。

因此,两者的区别取决于语言语义和工具,而不只是文档是否出现在源文件中。

局限与维护

文档字符串通常不会约束程序的执行。声明某个参数必须为正数,只是在提供说明;除非实现代码或其他机制对此进行检查,否则它并不构成校验。

随着代码变化,文档也可能与实际行为发生偏离。因此,在审查实现变更时一并审查文档字符串,是软件工程实践的一部分。可执行示例和文档检查能够发现某些不一致之处,但无法验证每一项自然语言表述。

并非所有构建配置都保证文档字符串在运行时可用。Python 的 -OO 优化选项会丢弃已识别的文档字符串,因此,依赖文档字符串存在的程序在使用该选项时,行为可能有所不同。

文档生成过程也会影响程序的运行。通过导入模块来检查其对象的工具,可能会执行模块级代码。基于源代码的提取方式可以避免部分导入时的影响,但可能无法获取运行时动态创建的信息。这些方法需要在文档的完整性与加载被记录程序所带来的影响之间作出不同的权衡。