标签: docstring

当函数没有返回任何内容时,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

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

有没有办法以类似于docstring描述模块或功能的方式描述模块的数据？

class MyClass(object):
    def my_function():
        """This docstring works!"""
        return True
    my_list = []
    """This docstring does not work!"""

像pep8这样的工具可以查看源代码样式,但是它们不会根据pep257,pep287来检查docstrings是否已经过滤.有这样的工具吗？

更新

我决定自己实现这样一个静态分析工具,请参阅:

https://github.com/GreenSteam/pep257

现在,大多数pep257都被覆盖了.设计受到提到的pep8工具的严重影响.

我希望能够在PHP5对象中实现自定义注释,并且我想通过构建自己的解析器来了解整个过程是如何工作的.

但是,首先,我需要知道如何查找注释.

有没有我想念的反射方法,还是有另一种方法？

例如,我希望能够在类中找到以下注释:

/**
 * @MyParam: myvalue
 */

PEP 257说:

文档字符串处理工具将从文档字符串的第二行和更多行中删除均匀数量的缩进,等于第一行之后所有非空行的最小缩进.文档字符串第一行中的任何缩进(即,直到第一个换行符)都是无关紧要的并被删除.保留docstring中后续行的相对缩进.应从docstring的开头和结尾删除空行.

trim然后在PEP中显示实现该算法的功能.

我可以找到问题,人们会问如何格式化文档字符串,并参考PEP 257(例如,这).我还看到一些有关工具的信息,这些工具试图确保您的文档字符串遵循PEP 257(例如,此).我找不到的是任何Python库,它实际上是一个"文档字符串处理工具",以PEP 257中定义的方式处理文档字符串 - 或者至少,我找不到直接使这个文档字符串处理功能的工具可用.

trimPEP 257中显示的功能是否存在于标准库中？显然我可以自己将函数粘贴到文件中,但如果我使用其他需要此功能的计算机,而不是总是从PEP复制和粘贴,我宁愿在标准库中使用它.鉴于该功能是由BDFL共同编写的PEP,我原以为会有一些官方或半官方图书馆这样做.

我想要这个的原因是编写一个装饰器来做一些Python内部重新格式化类/函数的文档字符串.我不想生成HTML或其他任何东西; 我只想更改实际对象的实际文档字符串.我想获取__doc__Python对象的纯文本属性,并将其重新格式化为将用作Python对象的纯文本属性的东西__doc__.

我无法理解为什么python会出现"预期的缩进块"错误？

""" This module prints all the items within a list"""
def print_lol(the_list):
""" The following for loop iterates over every item in the list and checks whether
the list item is another list or not. in case the list item is another list it recalls the function else it prints the ist item"""

    for each_item in the_list:
        if isinstance(each_item, list):
            print_lol(each_item)
        else:
            print(each_item)

写这样的东西是有效的JavaScript:

function example(x) {
    "Here is a short doc what I do.";
    // code of the function
}

字符串实际上什么也没做.有什么理由,为什么不应该以这种方式在JavaScript中评论他/她的功能？

在讨论问题时我能想到的两点:

• 必须启动字符串文字,从长远来看这可能是昂贵的

• JS minifiers不会将字符串文字识别为可移除的

还有其他一点吗？

编辑:为什么我提出这个主题:我在John Resig的博客上发现了类似的东西,其中新的ECMA 5标准使用未分配的字符串文字来启用"严格模式".现在,我有兴趣进行评估,如果在进行此类文档时可能存在使用或危险.

如何将python doc字符串转码为Github readme.md？

虽然看起来似乎每个人都做了,我似乎无法得到一个像样的解决方案,我认为它应该很容易,所以似乎人们不太可能抛出两个转换器......

我试过了什么

pydoc 其实很简单.pydoc的输出是联机帮助页(UNIX系统的groff格式).这是一个死胡同,因为男人对md不是一件事.通过HTML,pydoc3 -w+ pandoc,完全将文档字符串转换为位.

自定义代码似乎有很多简短的自定义代码,但对于少数我尝试过的输出似乎不如pydoc那样好,它有一个摘要,添加了继承的方法并列出了一些属性.

mkdocs.有人建议在某处.它只会污染我的文件夹,因为它是一个误导性的名称,因为它不是docstrings> md转换器,而是md> html.

狮身人面像+潘多克.在解决了UTF-8问题之后,我放弃了Sphinx,因为我有一个要转换的py脚本,并且快速启动的autodoc设置没有解析我的脚本.我尝试用Python导入sphinx.ext.autodoc但TBH的文档太长了,我放弃了.

NB

有一个[一年前未解答的SO问题](从Python Docstrings自动生成GitHub Wiki文档)关于这个主题,但我希望通过提供更多细节我会得到答案.

从文档中可以看出,双引号用于文字,而单引号则在有代码文本被解释时使用.

这将导致我为f()下面的方法编写docstring :

class A(B):

    def f(arg1, arg2):
        return B(arg1 + arg2 + self.index)

如:

Takes two arguments, ``arg1` and ``arg2``, which are assumed to be objects
of type (or duck-type) `NiceClass`, and returns a new object of class `B`
with `B.something` assigned some hash of ``arg1`` and ``arg2``.

这是正确的吗？

在许多代码示例中,Sphinx和其他方面,我看到相当于B并NiceClass用双引号括起来("``B``"和"``NiceClass``").