如何使用參數記錄方法？

Question

如何使用Python的文檔字符串來記錄具有參數的方法？

編輯： PEP 257給出了這樣的例子：

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    Keyword arguments: 
    real -- the real part (default 0.0) 
    imag -- the imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

這是大多數Python開發者使用的慣例？

Keyword arguments: 
<parameter name> -- Definition (default value if any) 

我期待更多的東西一點點正式比如

def complex(real=0.0, imag=0.0): 
    """Form a complex number. 

    @param: real The real part (default 0.0) 
    @param: imag The imaginary part (default 0.0) 

    """ 
    if imag == 0.0 and real == 0.0: return complex_zero 
    ... 

Environement：Python的2.7.1

Answer 1

根據我的經驗，numpy docstring conventions（PEP257超集）是最廣泛流傳其次慣例，它們也通過工具的支持，如Sphinx。

一個例子：

Parameters 
---------- 
x : type 
    Description of parameter `x`. 

Answer 2

約定：

• PEP 257 Docstring Conventions
• PEP 287 reStructuredText Docstring Format

工具：

• Epydoc: Automatic API Documentation Generation for Python
• sphinx.ext.autodoc – Include documentation from docstrings
• PyCharm has some nice support for docstrings

---

更新：因爲Python 3.5，你可以使用type hints這是一個結構緊湊，機器可讀的語法：

from typing import Dict, Union 

def foo(i: int, d: Dict[str, Union[str, int]]) -> int: 
    """ 
    Explanation: this function takes two arguments: `i` and `d`. 
    `i` is annotated simply as `int`. `d` is a dictionary with `str` keys 
    and values that can be either `str` or `int`. 

    The return type is `int`. 

    """ 

這句法的主要優點是，它是由語言定義的，它是明確的，所以像PyCharm工具，可以輕鬆地從它的優勢。

Answer 3

python doc字符串是自由格式，您可以用任何您喜歡的方式記錄它。

例子：

def mymethod(self, foo, bars): 
    """ 
    Does neat stuff! 
    Parameters: 
     foo - a foo of type FooType to bar with. 
     bars - The list of bars 
    """ 

現在，有一些約定，但是Python不強制任何人。有些項目有自己的約定。一些使用docstrings的工具也遵循特定的約定。

Answer 4

Docstrings僅在交互式環境中有用，例如， Python shell。當記錄不會交互使用的對象時（例如內部對象，框架回調），您不妨使用常規註釋。這是一種風格我用掛項目縮進的意見，每個對自己行，所以你知道註釋適用於：

def Recomputate \ 
    (
    TheRotaryGyrator, 
     # the rotary gyrator to operate on 
    Computrons, 
     # the computrons to perform the recomputation with 
    Forthwith, 
     # whether to recomputate forthwith or at one's leisure 
) : 
    # recomputates the specified rotary gyrator with 
    # the desired computrons. 
    ... 
#end Recomputate 

你不能做這樣的事情有文檔字符串。

Answer 5

如果你打算使用獅身人面像來記錄你的代碼，它能夠很好地產生HTML格式文檔，以便與他們的「簽名」功能的參數。 http://sphinx-doc.org/domains.html#signatures

Answer 6

其他答案在這裏已經指出，可能與Sphinx way一起使用，以便您可以使用Sphinx在稍後生成那些奇特的文檔。

這就是說，我個人會偶爾使用內聯評論風格。

def complex( # Form a complex number 
     real=0.0, # the real part (default 0.0) 
     imag=0.0 # the imaginary part (default 0.0) 
     ): # Returns a complex number. 
    """Form a complex number. 

    I may still use the mainstream docstring notation, 
    if I foresee a need to use some other tools 
    to generate an HTML online doc later 
    """ 
    if imag == 0.0 and real == 0.0: 
     return complex_zero 
    other_code() 

這裏再舉一個例子，有一些微小的細節記錄在線：

def foo( # Note that how I use the parenthesis rather than backslash "\" 
      # to natually break the function definition into multiple lines. 
     a_very_long_parameter_name, 
      # The "inline" text does not really have to be at same line, 
      # when your parameter name is very long. 
      # Besides, you can use this way to have multiple lines doc too. 
      # The one extra level indentation here natually matches the 
      # original Python indentation style. 
      # 
      # This parameter represents blah blah 
      # blah blah 
      # blah blah 
     param_b, # Some description about parameter B. 
      # Some more description about parameter B. 
      # As you probably noticed, the vertical alignment of pound sign 
      # is less a concern IMHO, as long as your docs are intuitively 
      # readable. 
     last_param, # As a side note, you can use an optional comma for 
        # your last parameter, as you can do in multi-line list 
        # or dict declaration. 
     ): # So this ending parenthesis occupying its own line provides a 
      # perfect chance to use inline doc to document the return value, 
      # despite of its unhappy face appearance. :) 
    pass 

的好處（如@標記霍瓦特已在其它評論指出）是：

• 最重要的是，參數和他們的文檔始終保持在一起，這帶來以下好處：
• 減少打字（無需重複變量名稱）
• 更改/刪除變量時更易於維護。重命名某些參數後，絕不會有一些孤兒參數doc段落。
• 和更容易找到缺少的評論。

現在，有人可能會認爲這種風格看起來很「醜陋」。但我會說「醜」是一個主觀詞。更加中性的方式是說，這種風格不是主流，所以它可能看起來不太熟悉，因此不太舒服。再次，「舒適」也是一個主觀詞彙。但重要的是，上述所有的好處都是客觀的。你不能以標準的方式實現它們。

希望未來有一天，會有一個文檔生成器工具，它也可以使用這種內聯樣式。這將推動採用。

PS：這個答案來源於我自己喜歡的每當我認爲合適時使用內嵌評論。我也使用same inline style to document a dictionary。

Answer 7

由於docstrings是自由形式的，它實際上取決於你用什麼來解析代碼來生成API文檔。

我會建議得到熟悉Sphinx markup，因爲它被廣泛應用，併成爲記錄Python項目，部分是因爲出色的readthedocs.org服務的事實標準。爲了paraphrase an example從獅身人面像的文件爲Python代碼片段：

def send_message(sender, recipient, message_body, priority=1): 
    ''' 
    Send a message to a recipient 

    :param str sender: The person sending the message 
    :param str recipient: The recipient of the message 
    :param str message_body: The body of the message 
    :param priority: The priority of the message, can be a number 1-5 
    :type priority: integer or None 
    :return: the message id 
    :rtype: int 
    :raises ValueError: if the message_body exceeds 160 characters 
    :raises TypeError: if the message_body is not a basestring 
    ''' 

此標記支持文件多間cross-referencing。請注意，Sphinx文檔使用（例如）:py:attr:，而您可以在從源代碼記錄時僅使用:attr:。

當然，還有其他工具可以記錄API。還有更經典的Doxygen，它使用\paramcommands，但這些並不是專門設計用來像Sphinx那樣記錄Python代碼的。

注意，有一個similar question在這裏similar answer ...