用于条件返回的python docstring

Question

为有条件地返回某些内容或NoneType 的函数编写文档字符串的约定是什么？我看到使用 Sphinx 可能与此相关的帖子，但我想知道以下代码中格式的约定是什么：

def some_func(input):
    """
    Some docstring

    Parameters
    ----------
    input : float
        Some float

    Returns
    -------
    float
        if condition met: the result
    NoneType
        if condition not met: NoneType
    """
    if input > 0.5:
        return input*100
    else:
        return

Answer 1

没有单一样式的文档字符串；不同的项目以不同的方式构建它们，因此如果没有现有的如何处理此问题的示例，您应该随意使用适合您的任何东西。

PEP-257 概述了一些应遵循的一般准则，最明显

函数或方法的文档字符串应总结其行为并记录其参数、返回值、副作用、引发的异常以及何时可以调用的限制（如果适用）。应指明可选参数。应该记录关键字参数是否是接口的一部分。

我觉得你写的很好。

作为记录，您不需要 else 块。没有显式返回的 Python 函数将返回 None。此外，返回的if 块实际上不需要else，因为只有在不满足条件时才会执行它们之后的代码。