Question

我正在为我编写的软件包添加一些（epydoc）文档，而且我遇到了很多我多次重复自己的实例。

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}
    """

PEP257说：

单行是非常明显的案例。

以及

函数或方法的docstring应该总结其行为并记录其参数，返回值，副作用，引发的异常以及何时可以调用它们的限制（所有这些都适用）。

是否有关于何时在单线（描述）和完整参数/返回字段之间划线的一般准则或标准做法？

或者在生成文档时，我应该为每个函数包含每个适用的字段，而不管它看起来多么重复？

奖金问题：从语法上讲，描述script参数的最佳方式是什么？

Answer 1

您正在寻找的一般准则是PEP257所引用的内容，也许您只需要看到它的实际效果。

您的函数是单行文档字符串（“非常明显的情况”）的理想选择：

def script_running(self, script):
    """Check if the script is running."""

通常，如果你说一个函数正在检查一些东西，那就意味着它会返回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."""

有时候 function-name-imagination 会被所有编码所厌倦，但你应该尝试尽力而为。

对于多行示例，让我借用google guidelines：

中的文档字符串

def fetch_bigtable_rows(big_table, keys, other_silly_variable=None):
    """Fetches rows from a Bigtable.

    Retrieves rows pertaining to the given keys from the Table instance
    represented by big_table.  Silly things may happen if
    other_silly_variable is not None.

    Args:
        big_table: An open Bigtable Table instance.
        keys: A sequence of strings representing the key of each table row
            to fetch.
        other_silly_variable: Another optional variable, that has a much
            longer name than the other args, and which does nothing.

    Returns:
        A dict mapping keys to the corresponding table row data
        fetched. Each row is represented as a tuple of strings. For
        example:

        {'Serak': ('Rigel VII', 'Preparer'),
         'Zim': ('Irk', 'Invader'),
         'Lrrr': ('Omicron Persei 8', 'Emperor')}

        If a key from the keys argument is missing from the dictionary,
        then that row was not found in the table.

    Raises:
        IOError: An error occurred accessing the bigtable.Table object.
    """

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

您可能也有兴趣看一下example of pypi project要记录的Sphinx。

我的2美分：指南旨在让您了解应该做什么和不该做什么，但他们并非严格的规则，你必须盲目地跟随。所以最后选择你感觉更好的东西。

我想澄清一下在另一个答案中所说的关于用文档字符串命中 最大行长度 的内容。

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

这是80个字符：

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

这可能是一个边缘情况，你真正需要的只是一个长句：

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

    """

就像一行文档字符串，意思是用于非常明显的情况，但在你的编辑器上（80字符串限制）是多行的。

Answer 2

我认为在为文档字符串添加扩展语法时可能总会有一定程度的重复，即epydoc / sphinx标记。

我也会说这件事主观而不是客观。显式优于隐式，并且似乎更符合Python的Zen。

Docstrings - 一行与多行

2 个答案: