Python 中最常见的 Docstring 模式
记录代码是一个好习惯，有抱负的开发人员和程序员应该养成在编码之旅的早期阶段记录代码的习惯。
记录源代码可以提高源代码的可读性和管理能力，并使源代码的新贡献者非常容易理解它。
文档字符串是写在源代码中的字符串文字。它们充当代码片段的注释或文档。文档字符串用于描述类、函数，有时甚至是文件。
换句话说，文档字符串充当有关代码片段的元数据。一个文档字符串包含所有关于它们所描述内容的相关信息。对于一个类，它包含以下信息：
- 班上
- 类函数
- 类属性。
对于函数，它包含有关以下内容的详细信息：
- 参数
- 参数的数据类型
- 参数的默认值
- 关于参数的简短描述
- 函数返回什么
- 函数返回的数据类型
- 函数引发的错误和异常以及有关的简短描述
专业的 Python 开发人员使用几种文档字符串模式来记录他们的代码。
可以创建他们的文档字符串模式，而不是使用现有的。不过，这个决定完全取决于个人开发人员或开发人员团队。
本文将讨论 Python 编程语言的最佳文档字符串模式。
Python 中的文档字符串模式
以下是 Python 专业人士在行业中常用的一些最佳文档字符串模式。
Epytext 模式
Epytext 模式是一种类似于 JavaDoc 的文档字符串模式。它是 Epydoc 工具的一部分，用于使用其文档字符串为 Python 模块生成文档。以下是 Epytext 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""
顶部提供了该功能的简要说明。
所有函数参数都使用 @param 关键字编写。函数返回内容的解释写在 @return 关键字旁边。
如果函数引发错误或异常，则使用 @raise 关键字编写它们。
休息模式
reSt 或 reStructuredText 是 Sphinx 使用的一种文档字符串模式，Sphinx 是一种用于为 Python 编程语言生成文档的工具。此模式是 IT 行业中最常用的文档字符串模式之一。
该方法还用作 Pyment 中的输出格式，这是一种帮助 Python 程序员使用文档字符串编写增强代码文档的工具。当代码部分记录或不包含文档字符串时，此工具很有用。
JetBrains PyCharm IDE 或集成开发环境也使用 reST 模式。以下是 reST 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""
与 Epytext 模式类似，除了在 Epytext 模式中使用冒号或 : 作为关键字的前缀而不是 at 符号或 @ 之外，此模式的所有内容都相同。
该方法的简明或全面描述位于顶部。所有参数都位于 :param 关键字旁边。该方法返回的内容的解释写在 :return 关键字旁边。
并且，所有错误的详细信息都放在 :raise 关键字旁边。
谷歌模式
列表中的另一个模式是 Google 模式。从技术上讲，它的名字不是谷歌的模式，而是谷歌开发的模式。
这是一种在标题下组织细节的简洁模式。Sphinx 工具也能够识别这种模式并生成文档。
这种模式也是最多的文档字符串模式之一。以下是 Google 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Args:
parameter1: this is the first parameter.
parameter2: this is the second parameter.
Returns:
this is a description of what is returned by the function.
Raises:
KeyError: raises an exception.
TypeError: raises an exception.
"""
与前面的模式一样，该方法的简洁描述位于顶部。
描述之后是诸如 Args、Returns 和 Raises 之类的标题。在 Args 标题下，放置了所有参数和详细信息，例如它们的类型和默认值。
函数返回内容的描述放在 Returns 标题下。最后，错误或异常及其详细信息写在 Raises 标题下。
Numpydoc 模式
numpy 模块具有称为 Numpydoc 模式的文档字符串模式。
该模式类似于 Google 模式，可以被 Sphinx 工具识别。与 Google 模式类似，信息按标题组织。
以下是 Numpydoc 模式的示例。
"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.
Parameters
----------
parameter1 : int
this is the first parameter.
parameter2 : str, "default value"
this is the second parameter.
Returns
-------
string
returns a string value.
Raises
------
KeyError
raises an exception.
TypeError
raises an exception.
"""
方法的描述写在顶部。有关该方法的其他详细信息在标题下组织：Parameters、Returns 和 Raises。
有关参数的所有详细信息，包括它们的默认值、值类型等，都放在 Parameters 标题下。关于函数返回内容的所有详细信息，包括数据类型，都位于 Returns 标题下。
最后，关于错误或异常的信息和一些描述写在 Raises 标题下。
