我在哪里可以找到适当的PEP 257 Docstring惯例示例？

PEP 257 says：我在哪里可以找到适当的PEP 257 Docstring惯例示例？

之前和记录一个类中的所有文档字符串（单行或多线）之后插入空行 - 一般来说，该类的方法由单个彼此分开空白行，并且 docstring需要通过空行偏移第一个方法; 为对称，在类标题和文档字符串之间放置一个空行。

但我似乎无法找到任何代码，实际上实现了这一点。

我已经检查了几个与Python 2.6交付的标准模块，甚至专门为那些提到Guido的名字而搜索的模块。但即使是里特维尔德代码检查工具的代码就恕我直言不符合（见例如http://code.google.com/p/rietveld/source/browse/upload.py）：

class CondensedHelpFormatter(optparse.IndentedHelpFormatter): 
    """Frees more horizontal space by removing indentation from group 
     options and collapsing arguments between short and long, e.g. 
     '-o ARG, --opt=ARG' to -o --opt ARG""" 

    def format_heading(self, heading): 
    return "%s:\n" % heading

这种多行文档字符串并没有在之前的空行，空行后收盘报价外。

/usr/lib64/python2.6/site.py这个类没有空行，但在结束引号之前和之后有一个空行。

class _Helper(object): 
    """Define the built-in 'help'. 
    This is a wrapper around pydoc.help (with a twist). 

    """ 

    def __repr__(self):

是否有可用于演示PEP 257的示例？

在此先感谢

来源

2012-04-04 Bram

“List of”/“Poll”问题不是Stack Overflow的主题。另外，我不明白这与你想要解决的实际问题有什么关系。 – agf 2012-04-04 19:23:01

我很欣赏你所做的研究，当然也可以找到官方文档字符串格式的例子，但不清楚它会带来什么好处。有不正确的docstrings的例子，其中一些甚至可能是由圭多写的。如果你想写出正确的，只需遵循指导方针（PEP文件本身甚至给出了例子）。总之，这里有什么意义？为什么你需要（更多）这种格式的例子？ – 2012-04-04 19:35:11

@agf：这不是一个民意调查。我相信PEP在某些领域并不是100％清晰的，我正在寻找可以澄清这些部分的例子。具体来说，我喜欢与PEP匹配的类的文档字符串示例。 Halst的代码在类docstring之前和之后显示空行，以及在文档字符串本身结尾的空行。这是我甚至没有考虑过的另一种选择。 – Bram 2012-04-11 09:41:04

不是一个直接的答案，但如果你想以符合PEP257你可以使用一个工具，我写道： https://github.com/halst/pep257

我太震惊地看到多少代码（也在标准库中）甚至不尝试遵守PEP257。

也许，大多数人认为他们文档字符串风格是有道理的，我还以为有什么尴尬的PEP257风格，但使用了一段时间我就爱上了它，后认为这是写文档最美丽的方式。我始终遵循PEP257的各个方面，并编写该工具，以便更多人能够看到他们如何改进他们的风格。

举个例子，我曾与PEP8和pep8 tool一个有趣的经历：当我第一次读到PEP8我喜欢它，认为我跟着它，但是当我试图在PEP8 我的代码被多远从震惊PEP8我是，在修复这些风格错误之后，我的代码看起来更好。

我希望人们会有与pep257类似的经历，从此开始追随PEP257。

来源

2012-04-08 19:35:14 Halst

谢谢，这肯定会有所帮助。它已经显示你对PEP的解释与我的略有不同。 – Bram 2012-04-11 09:35:15

@Bram有趣！你对PEP的哪些部分有不同的解释？只是好奇。也许在我的解释中有一个错误。 – Halst 2012-04-11 11:04:08

在阅读你的pep257.py之前，我从来没有考虑过**和**之前的空行。 – Bram 2012-04-11 19:09:25

据我所看到的，你链接到文件说：

插入一个空行后所有文档字符串（一行或多行），该文件的一类 - 一般来说，类的方法通过一个空白行彼此分开，并且docstring需要通过空行偏移第一个方法。

（重点煤矿）

所以，你给的例子是正确的，因为他们有文档字符串后，一个空行，从而分离以一个空行的下一个方法声明。

来源

2015-03-04 12:23:59

我在哪里可以找到适当的PEP 257 Docstring惯例示例？

回答

相关问题