Question

我正在编写以下函数：

def parse_zip_file(path, handler):
    """
    Parse all files contained in a zip file (specified by the path parameter).

    Parameters
    ----------
    path : str
        The path to the zip file.
    handler: function
        When looping through all the files contained in the zip file, this method will be called every time
        a new file is found. Two arguments are passed. The first argument is the name of the discovered file
        and the second argument are the contents of the file.

    Returns
    -------
    None
        Nothing is returned.
    """
    return None

我在想，我这样做是否正确？有什么方法可以检查docstring是否正确（我使用PyCharm作为编辑器）？更具体地说，function是处理程序参数的正确类型吗？在哪里可以找到我可以使用的所有NumPy文档字符串类型的概述？如果根本没有返回任何内容，我使用None是否正确？

Answer 1

我也有同样的问题。这个 question 非常相似，接受的答案说要包含它，但并没有真正说明为什么或为什么不这样做，也没有回答您关于在哪里验证您的工作的特定问题。

验证文档字符串的高级答案是来自 NumPy 的 documentation。

这可能已经足够了，但请继续阅读此问题中的小问题的答案。第一：

<块引用>

我想知道，我这样做正确吗？有什么办法可以检查文档字符串是否正确（我使用 PyCharm 作为编辑器）？

来自 NumPy 的这个 page 有一个很好的关于验证的部分。你可以用 numpydoc 做到这一点。

<块引用>

要查看为对象生成的重组文本，可以调用 numpydoc 模块。例如，要为 numpy.ndarray 执行此操作，请使用：

$ python -m numpydoc numpy.ndarray

其他选项，可以使用 sphinx，另一个包是 pydocstyle - 虽然我不能说它的覆盖范围，但它看起来确实得到维护，通过 Python 3.9 支持。

<块引用>

更具体地说，函数是处理程序的正确类型争论？

我相信是这样，我没有看到关于哪些类型有效的特定部分，我假设所有类型都是有效的，并且函数是有效的类型/类。

<块引用>

在哪里可以找到我可以使用的所有 NumPy 文档字符串类型的概述？

Top level docs。

<块引用>

如果根本没有返回任何东西，我使用 None 是否正确？

是的。文档说明如下，重点是我自己的：

<块引用>

退货

返回值及其类型的说明。类似于参数部分，除了每个返回值的名称是可选的。 始终需要每个返回值的类型：

Answer 2

docstrings是在pycharm中使用""" """自动生成的，并且在声明返回类型的函数后使用Enter键:rtype: None

函数类型和无类型的NumPy文档字符串

2 个答案: