169

私は現在Pythonを始めており、PHPのバックグラウンドが強く、PHPではjavadocドキュメントテンプレートとして使用する習慣があります。

Pythonのドキュメントjavadocとしての場所があるのだろうかと思っていました。ここで確立された慣習および/または公式のギルドラインは何ですか？docstring

たとえば、このようなものはPythonの考え方に合わせるには複雑すぎるのでしょうか、それともできるだけ簡潔にする必要がありますか？

"""
replaces template place holder with values

@param string timestamp     formatted date to display
@param string priority      priority number
@param string priority_name priority name
@param string message       message to display

@return string formatted string
"""

そして、私が少し網羅的すぎる場合は、代わりにこのようなものを使用する必要があります（ほとんどのドキュメントが__doc__メソッドを介して印刷されません）？

# replaces template place holder with values
#    
# @param string timestamp     formatted date to display
# @param string priority      priority number
# @param string priority_name priority name
# @param string message       message to display
#    
# @return string formatted string

def format(self, timestamp = '', priority = '', priority_name = '', message = ''):
    """
    replaces template place holder with values
    """
    values = {'%timestamp%' : timestamp,
              '%priorityName%' : priority_name,
              '%priority%' : priority,
              '%message%' : message}

    return self.__pattern.format(**values)
4

4 に答える 4

232

プレーンテキスト/docstringマークアップ形式であり、おそらくPythonの世界で最も人気のあるreStructuredText （「reST」とも呼ばれます）形式をご覧ください。そして、reStructuredTextからドキュメントを生成するツールであるSphinx（たとえば、Pythonドキュメント自体に使用される）を確認する必要があります。Sphinxには、コード内のdocstringからドキュメントを抽出する機能が含まれており（sphinx.ext.autodocを参照）、特定の規則に従ってreSTフィールドリストを認識します。これはおそらく最も人気のある方法になっています（またはなりつつあります）。

あなたの例は次のようになります：

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:param priority: priority number
:param priority_name: priority name
:param message: message to display
:returns: formatted string
"""

またはタイプ情報で拡張：

"""Replaces template placeholder with values.

:param timestamp: formatted date to display
:type timestamp: str or unicode
:param priority: priority number
:type priority: str or unicode
:param priority_name: priority name
:type priority_name: str or unicode
:param message: message to display
:type message: str or unicode
:returns: formatted string
:rtype: str or unicode
"""
于 2011-03-17T13:02:27.763 に答える
77

GooglePythonスタイルガイドに従ってください。Sphinxは、Sphinx 1.3にパッケージ化されているNapolean拡張機能を使用してこの形式を解析することもできることに注意してください（これはPEP257とも互換性があります）。

def func(arg1, arg2):
    """Summary line.

    Extended description of function.

    Args:
        arg1 (int): Description of arg1
        arg2 (str): Description of arg2

    Returns:
        bool: Description of return value

    """
    return True

上記のリンク先のナポレアンのドキュメントから抜粋した例。

ここにすべてのタイプのdocstringの包括的な例があります。

于 2014-12-01T16:10:53.357 に答える
25

Pythonドキュメント文字列の標準は、Python拡張提案257で説明されています。

メソッドの適切なコメントは次のようになります

def format(...):
    """Return timestamp string with place holders replaced with values.

    Keyword arguments:
    timestamp     -- the format string (default '')
    priority      -- priority number (default '')
    priority_name -- priority name (default '')
    message       -- message to display (default '')
    """
于 2011-03-17T03:40:14.340 に答える
1

「Pythonのドキュメントの作成者と潜在的な作成者を対象とした」ページであるDocumentingPythonをご覧ください。

要するに、reStructuredTextはPython自体を文書化するために使用されるものです。開発者ガイドには、reST入門書、スタイルガイド、および優れたドキュメントを作成するための一般的なアドバイスが含まれています。

于 2012-07-19T03:31:03.327 に答える