Python 文档字符串-单行与多行

我将一些（）文档添加到我编写的包中，并且我遇到了许多实例，在这些实例中我多次重复我自己

def script_running(self, script):
    """Return if script is running

    @param script: Script to check whether running

    @return: B{True} if script is running, B{False} otherwise
    @rtype: C{bool}
    """

他说：

一句话适用于非常明显的情况

而且

函数或方法的docstring应该总结其行为，并记录其参数、返回值、副作用、引发的异常以及何时可以调用它的限制（如果适用的话）

---

对于何时在一个线性（说明）字段和完整参数/返回字段之间划界，是否有一般指南或标准实践

或者在生成文档时，我是否应该包括每个功能的每个适用字段，而不管它看起来有多重复

---

附加问题：从语法上讲，描述

脚本
参数的最佳方式是什么
 我认为在为docstring添加扩展语法（即epydoc/sphinx标记）时，可能总会涉及一定程度的重复

我还要说，这件事是主观的，而不是客观的。显式比隐式好，而且似乎更多地遵循Python的禅宗思想。
您正在寻找的一般指导原则就在您引用的内容中，也许您只需要看到它的实际应用

您的函数是单行docstring（“非常明显的情况”）的最佳候选函数：

通常，如果您说某个函数正在检查某些内容，则意味着它将返回
True
或
False
，但如果您愿意，可以更具体地说：

def script_running(self, script):
    """Return True if the script is running, False otherwise."""

再一次，一切都在一行

我可能还会更改函数的名称，因为不需要强调函数名（脚本）中的功能。函数名应该是关于函数功能的甜美、简短和有意义的名称。也许我会选择：

def check_running(self, script):
    """Return True if the script is running, False otherwise."""

有时，所有的编码都会让函数名想象疲劳，但无论如何，您都应该尽力做到最好

对于多行示例，让我从以下位置借用docstring：

这可能是“总结其行为并记录其参数、返回值、副作用、引发的异常以及对何时可以调用它的限制（如果适用的话）的一种方式”

您可能也有兴趣看看这本书，它是用来记录的

我的2美分：指南旨在让你知道你应该做什么和不应该做什么，但它们并不是你必须盲目遵守的严格规则。所以在最后选择你觉得更好的


我想澄清另一个答案中关于使用docstring达到最大行长度的说法

告诉您“将所有行限制为最多79个字符”，即使最后每个人都有80个字符

这是80个字符：

--------------------------------------------------------------------------------

这可能是一个边缘案例，你真正需要的是一句稍微长一点的句子：

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 characters
    limit.
    
    """

类似于一行docstring，这意味着它适用于非常明显的情况，但在编辑器上（限制为80个字符）是多行的

--------------------------------------------------------------------------------

def my_long_doc_function(arg1, arg2):
    """This docstring is long, it's a little looonger than the 80 characters
    limit.
    
    """