标签: docstring

编写Python文档字符串的首选方法是什么？

""" 要么 "

在Dive Into Python一书中 ,作者提供了以下示例:

def buildConnectionString(params):
    """Build a connection string from a dictionary of parameters.

    Returns string."""

在另一章中,作者提供了另一个例子:

def stripnulls(data):
    "strip whitespace and nulls"
    return data.replace("\00", "").strip()

两种语法都有效.对我来说唯一的区别是"""允许我们编写多行文档.

除此之外有什么区别吗？

我正在针对 Python 脚本运行 Black 代码格式化程序，但它不会重新格式化文档字符串的行长度。例如，给出以下代码：

def my_func():
    """
    This is a really long docstring. This is a really long docstring. This is a really long docstring. This is a really long docstring. This is a really long docstring. This is a really long docstring.
    """
    return

当针对此脚本运行 Black 时，行长度不会改变。如何确保文档字符串在运行 Black 时得到格式化？

什么,在您看来是一个有意义的文档？你期望在那里描述什么？

例如,考虑这个Python类__init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

你觉得这有意义吗？发布您的好/坏示例供所有人知道(以及一般答案,以便可以接受).

在IPython中,我习惯写

功能(

然后敲击一个选项卡,获取docstring的内容和命名参数的列表.但是,自从我安装了IPython 2.0以来,这就停止了.有解释或知道修复吗？

因此,reStructuredText是 Python代码文档的推荐方法,如果你足够努力,你可以 在sphinx文档中找到 如何规范化你的函数签名文档.所有给出的示例都是单行的,但是如果参数描述是多行的,如下所示呢？

def f(a, b):
    """ Does something with a and b

    :param a: something simple
    :param b: well, it's not something simple, so it may require more than eighty
              chars
    """

那是什么语法/惯例？我应该缩进吗？它会破坏reSTructuredText渲染吗？

我注意到Clojure多行文档字符串似乎在大多数情况下都是手动格式化的,包括clojure.core中的那些.示例来自https://github.com/clojure/clojure/blob/master/src/clj/clojure/core.clj:

(defn flatten
  "Takes any nested combination of sequential things (lists, vectors,
  etc.) and returns their contents as a single, flat sequence.
  (flatten nil) returns an empty sequence."
  {:added "1.2"
   :static true}
  [x]
  (filter (complement sequential?)
          (rest (tree-seq sequential? seq x))))

这看起来很奇怪,因为它意味着不同的文档字符串将具有不同的换行长度等,需要手动维护.

有没有更好的方法来格式化多行文档字符串？

我没有找到关于应该在类和__init__文档字符串中记录什么的最佳实践.有时我发现构造函数参数已经在docstring类中记录,有时会在__init__docstring 中描述.我更喜欢在类docstring中描述构造,因为这是您在创建新实例时调用的内容.但是应该在__init__docstring方法中记录什么呢？

编辑:

我知道google styleguide和google docstring样式示例,但两者都没有回答我的问题.文档字符串样式的例子确实说

该__init__方法可以记录在类级别docstring中,也可以记录在__init__方法本身的docstring中.任何一种形式都是可以接受的,但这两种形式不应混合.选择一种约定来记录__init__方法并与之保持一致.

但是如果我选择将__init__函数的docstring 放入类级docstring中,那么__init__docstring 应该包含什么？

是否可以计算 Python 文档字符串？我的文档字符串中有很多重复的内容，因此我想使用 f 字符串或 % 样式格式表达式。

当我在文档字符串的位置使用 f 字符串时

• 导入模块会调用处理
• 但是当我检查__doc__ 这样一个函数时它是空的
• 当文档字符串是 f 字符串时 sphinx barfs

我确实知道如何在导入后处理文档字符串，但这不适用于 sphinx 识别的对象“doc”字符串，但它不是__doc__对象的真实字符串。

当函数没有返回任何内容时,docstring约定是什么？

例如:

def f(x):
    """Prints the element given as input

    Args:
        x: any element
    Returns:
    """
    print "your input is %s" % x
    return

Returns:在docstring中我应该添加什么？没有现在的样子？

有时Python中的函数可能接受灵活类型的参数.或者它可以返回灵活类型的值.现在我不记得现在这样一个功能的一个很好的例子,因此我在下面用玩具示例展示这样的功能可能是什么样子.

我想知道如何使用Sphinx文档表示法为这些函数编写文档字符串.在下面的示例中,参数可以是str或int.同样,它可能会返回str或int.

我给出了一个示例文档字符串(两者都是默认的Sphinx表示法以及Sphinx拿破仑扩展所理解的Google表示法).我不知道这是否是记录灵活类型的正确方法.

Sphinx默认表示法:

def add(a, b):
    """Add numbers or concatenate strings.

    :param int/str a: String or integer to be added
    :param int/str b: String or integer to be added
    :return: Result
    :rtype: int/str
    """
    pass

狮身人面像拿破仑谷歌记号:

def add2(a, b):
    """Add numbers or concatenate strings.

    Args:
      a (int/str): String or integer to be added
      b (int/str): String or integer to be added

    Returns:
      int/str: Result
    """
    pass

在文档字符串中表达多个类型的参数或返回值的正确方法是什么？