问题描述

我在Python中看到了几种不同样式的文档字符串，最流行的样式是什么？

---

解决方案

格式

Python文档字符串可以按照其他帖子中显示的几种格式编写。但是，没有提到默认的Sphinx文档字符串格式，该格式基于睡觉。您可以在this blog post中获取有关主要格式的一些信息。

请注意，PEP 287推荐使用睡觉

以下是文档字符串的主要使用格式。

-电子邮件

历史上流行的是类似javadoc样式，因此将其作为Epydoc(称为Epytext格式)生成文档的基础。

示例：

"""
This is a javadoc style.

@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise keyError: raises an exception
"""

-睡觉

现在，可能更流行的格式是Sphinx用来生成文档的reStructiredText(睡觉)格式。 注意：在JetBrains PyCharm中默认使用它(定义方法后键入三重引号并按Enter键)。默认情况下，它也用作pyment中的输出格式。

示例：

"""
This is a reST style.

:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises keyError: raises an exception
"""

-Google

Google有自己的经常使用的format。它也可以由狮身人面像(即.使用Napoleon plugin)。

示例：

"""
This is an example of Google style.

Args:
    param1: This is the first param.
    param2: This is a second param.

Returns:
    This is a description of what is returned.

Raises:
    KeyError: Raises an exception.
"""

偶数more examples

-Numpydoc

请注意，Numpy推荐遵循他们自己的numpydoc，基于Google格式，可由Sphinx使用。

"""
My numpydoc description of a kind
of very exhautive numpydoc format docstring.

Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'

Returns
-------
string
    a value in a string

Raises
------
KeyError
    when a key error
OtherError
    when an other error
"""

转换/生成

可以使用像Pyment这样的工具自动生成尚未记录的Python项目的文档字符串，或者将现有文档字符串(可以混合多种格式)从一种格式转换为另一种格式。

注意：示例取自Pyment documentation