Python Docstring：提高与提高

Question

我使用PyCharm IDE协助制作符合PEP0257标准的文档字符串。它提供了两个属性，我不完全理解它们之间的区别/用法：

• :raise Exception: exception explanation here
• :raises Exception: exception explanation here

我什么时候会在我的文档字符串中使用raise作为raises的反对者？具体来说，如果一个类需要一个未提供的参数并引发一个TypeError，应该用它来记录它？

Answer 1

<强> TL; DR

raises用于描述可能引发的异常。运行autodoc时，Sphinx会识别raise，与raises相同。

完整说明

PyCharm有助于使用几种不同风格的文档字符串注释。

我经常使用的是：

1. NumPy Format
2. Google Format
3. Sphinx（远远超过格式）

在所有这些中，Raises有一个特殊部分，您可以在较旧版本的PyCharm代码测试中看到：

1. Simple NumPy
2. Simple Google

SphinxDocString的实施我们可以see here那里有许多可以识别的关键字。然后，这些标记会链接到RAISES_TAGS的列表，可以找到here。

我希望这些信息有用。

Answer 2

这对我感兴趣的任何人都可以在最新版本的PyCharm中使用。

"""
Some explanations.

:raises WhatEverError: if there is any error
"""

Answer 3

您必须使用raises来描述您的方法/类引发的异常。

:raises:
    Exception: Explanation here.

例如，对于ValueError异常：

:raises:
    ValueError: if fft_data is empty.