我在哪裏可以找到適當的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慣例示例？

回答

相關問題