Python文档字符串
Python文档字符串（或文档字符串）提供了一种将文档与Python模块、函数、类和方法相关联的便捷方式。
它在源代码中指定，用于记录特定代码段，如注释。与传统的源代码注释不同，文档字符串应该描述函数的作用，而不是如何。
文档字符串应该是什么样的？
- 文档字符串行应以大写字母开头并以句点结尾。
- 第一行应该是简短的描述。
- 如果文档字符串中有更多行，则第二行应为空白，从视觉上将摘要与描述的其余部分分开。
- 以下几行应该是描述对象的调用约定、副作用等的一个或多个段落。
声明文档字符串：文档字符串在类、方法或函数声明的下方使用“三单引号”或“三双引号”来声明。所有函数都应该有一个文档字符串。
访问文档字符串：可以使用对象的 __doc__ 方法或使用帮助函数来访问文档字符串。
下面的示例演示了如何声明和访问文档字符串。
示例 1：使用三重单引号
def my_function():
'''Demonstrates triple double quotes
docstrings and does nothing really.'''
return None
print("Using __doc__:")
print(my_function.__doc__)
print("Using help:")
help(my_function)
输出：
Using __doc__:
Demonstrates triple double quotes
docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:
my_function()
Demonstrates triple double quotes
docstrings and does nothing really.
示例 2：使用三重双引号
def my_function():
"""Demonstrates triple double quotes
docstrings and does nothing really."""
return None
print("Using __doc__:")
print(my_function.__doc__)
print("Using help:")
help(my_function)
输出：
Using __doc__:
Demonstrates triple double quotes
docstrings and does nothing really.
Using help:
Help on function my_function in module __main__:
my_function()
Demonstrates triple double quotes
docstrings and does nothing really.
单行文档字符串
顾名思义，一行文档字符串适合一行。它们用于明显的情况。结束引号与开始引号在同一行。这对于单线来说看起来更好。
例如：
def power(a, b):
"""Returns arg1 raised to power arg2."""
return a**b
print(power.__doc__)
输出：
Returns arg1 raised to power arg2.
多行文档字符串
多行文档字符串由一个摘要行组成，就像单行文档字符串一样，然后是一个空行，然后是更详细的描述。摘要行可能与开盘报价在同一行或在下一行。
下面的示例显示了一个多行文档字符串。
def my_function(arg1):
"""
Summary line.
Extended description of function.
Parameters:
arg1 (int): Description of arg1
Returns:
int: Description of return value
"""
return arg1
print(my_function.__doc__)
输出：
Summary line.
Extended description of function.
Parameters:
arg1 (int): Description of arg1
Returns:
int: Description of return value
文档字符串中的缩进
整个文档字符串的缩进与第一行的引号相同。文档字符串处理工具将从文档字符串的第二行和后面的行中去除均匀的缩进量，等于第一行之后所有非空行的最小缩进量。文档字符串第一行中的任何缩进（即，直到第一个换行符）都是微不足道的并被删除。保留文档字符串中后面几行的相对缩进。
类中的文档字符串
让我们举个例子来展示如何为一个类及其方法编写文档字符串。 help用于访问文档字符串。
class ComplexNumber:
"""
This is a class for mathematical operations on complex numbers.
Attributes:
real (int): The real part of complex number.
imag (int): The imaginary part of complex number.
"""
def __init__(self, real, imag):
"""
The constructor for ComplexNumber class.
Parameters:
real (int): The real part of complex number.
imag (int): The imaginary part of complex number.
"""
def add(self, num):
"""
The function to add two Complex Numbers.
Parameters:
num (ComplexNumber): The complex number to be added.
Returns:
ComplexNumber: A complex number which contains the sum.
"""
re = self.real + num.real
im = self.imag + num.imag
return ComplexNumber(re, im)
help(ComplexNumber) # to access Class docstring
help(ComplexNumber.add) # to access method's docstring
输出：
Help on class ComplexNumber in module __main__:
class ComplexNumber
| This is a class for mathematical operations on complex numbers.
|
| Attributes:
| real (int): The real part of complex number.
| imag (int): The imaginary part of complex number.
|
| Methods defined here:
|
| __init__(self, real, imag)
| The constructor for ComplexNumber class.
|
| Parameters:
| real (int): The real part of complex number.
| imag (int): The imaginary part of complex number.
|
| add(self, num)
| The function to add two Complex Numbers.
|
| Parameters:
| num (ComplexNumber): The complex number to be added.
|
| Returns:
| ComplexNumber: A complex number which contains the sum.
Help on method add in module __main__:
add(self, num) unbound __main__.ComplexNumber method
The function to add two Complex Numbers.
Parameters:
num (ComplexNumber): The complex number to be added.
Returns:
ComplexNumber: A complex number which contains the sum.
Python注释和文档字符串的区别
大家一定对Python文档字符串有所了解，但您有没有想过Python注释和文档字符串之间有什么区别。让我们来看看它们。
Python注释是开发人员提供的有用信息，可帮助读者理解源代码。它解释了代码中使用的逻辑或其中的一部分。它是使用#符号编写的。
例子：
# Python program to demonstrate comments
print("GFG")
输出：
GFG而上面提到的Python Docstrings 提供了一种将文档与Python模块、函数、类和方法相关联的便捷方式。