Docstrings - 一行与多行

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

有时功能名称想象力会被所有编码所累,但你应该尝试尽力而为.

对于多行示例,让我借用Google指南中的文档字符串:

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

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

您可能也有兴趣看看这个pypi项目的例子,它意味着要用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.