Python - 文档字符串

---

在 Python 中，文档字符串是一个字符串文字，用作不同 Python 对象（例如函数、模块、类及其方法和包）的文档。它是所有这些构造定义中的第一行，并成为 __doc__ 属性的值。

函数的文档字符串

def addition(x, y):
   '''This function returns the sum of two numeric arguments'''
   return x+y
print ("Docstring of addition function:", addition.__doc__)

它将产生以下输出-

Docstring of addition function: This function returns the sum of two numeric arguments

文档字符串可以用单引号、双引号或三引号编写。但是，大多数时候您可能需要描述性文本作为文档，因此使用三引号是理想的选择。

所有内置模块和函数都具有返回其文档字符串的 __doc__ 属性。

数学模块的文档字符串

import math

print ("Docstring of math module:", math.__doc__)

它将产生以下输出-

Docstring of math module: This module provides access to the mathematical functions
 defined by the C standard.

内置函数的文档字符串

以下代码显示 random 模块中 abs() 函数和 randint() 函数的文档字符串。

print ("Docstring of built-in abs() function:", abs.__doc__)
import random

print ("Docstring of random.randint() function:",
random.randint.__doc__)

它将产生以下输出 -

Docstring of built-in abs() function: Return the absolute value of the
argument.

Docstring of random.randint() function: Return random integer in range
[a, b], including both end points.

内置类的文档字符串

内置类的文档字符串通常更具解释性，因此文本跨多行。下面，我们检查内置 dict 类的文档字符串

print ("Docstring of built-in dict class:", dict.__doc__)

它将产生以下输出-

Docstring of built-in dict class: dict() -> new empty dictionary
dict(mapping) -> new dictionary initialized from a mapping object's
   (key, value) pairs
dict(iterable) -> new dictionary initialized as if via:
   d = {}
   for k, v in iterable:
      d[k] = v
dict(**kwargs) -> new dictionary initialized with the name=value pairs in the keyword argument list. For example: dict(one=1, two=2)

模板类的文档字符串

模板类定义在Python标准库的string模块中。它的文档字符串如下 -

from string import Template

print ("Docstring of Template class:", Template.__doc__)

它将产生以下输出-

Docstring of Template class: A string class for supporting $- substitutions.

帮助系统中的文档字符串

Python 的内置帮助服务也使用文档字符串。例如，检查Python解释器中abs()函数的帮助 -

>>> help (abs)
Help on built-in function abs in module builtins:
abs(x, /)
   Return the absolute value of the argument.

同样，在解释器终端中定义一个函数并运行 help 命令。

>>> def addition(x,y):
... '''addtion(x,y)
... Returns the sum of x and y
... '''
... return x+y
...
>>> help (addition)
Help on function addition in module __main__:
addition(x, y)
   addtion(x,y)
   Returns the sum of x and y

IDE 还使用 Docstring 在编辑代码时提供有用的类型提前信息。

文档字符串作为注释

出现在这些对象（函数、方法、类、模块或包）之外的任何地方的字符串文字都会被解释器忽略，因此它们类似于注释（以 # 符号开头）。

# This is a comment
print ("Hello World")
'''This is also a comment'''
print ("How are you?")