Pythonドキュメントでのjavadocの使用[終了]


162

私は現在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)

6
セラは、これが重複している前の質問でこれに対する多くのより多くの答えです。
Alex Dupuy 2014

回答:


227

プレーンテキスト/ドキュメント文字列のマークアップ形式であり、おそらくPythonの世界で最も人気のあるreStructuredText(「reST」とも呼ばれます)形式をご覧ください。そして、確かにreStructuredTextからドキュメントを生成するためのツールであるSphinxを確認する必要があります(たとえば、Pythonドキュメント自体に使用されます)。Sphinxには、コード内のドキュメント文字列からドキュメントを抽出する機能が含まれ(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
"""

7
長い説明のために改行する必要がある場合はどうしますか?どうですか?
Skylar Saveland 2012

6
特にreStructuredTextの参照、およびフィールドのリストを参照してください。docutils.sourceforge.net/docs/ref/rst/...
スティーブン

6
ここでのフレーズはPEP 257に準拠していないことに注意してください。それはなるべきであるReplace template place holder with values.代わりにreplaces template place holder with valuesお知らせ終わりの文章、開始時の大文字、およびピリオド(。) - 。
クラテンコ2014

1
バージョン1.3から、Sphinxはsphinx.ext.napoleon拡張機能を介してもう少し良い形式もサポートします。
ペトリ14

3
誰かが「:param ____:」や「:returns:」のようなこれらの特別なドキュメント文字列を指定する最高のドキュメントを私に指摘してもらえますか?現時点では、そのようなドキュメントを見つけるのはかなり難しいようです。
krumpelstiltskin 2016

75

Google Python Style Guideに従ってください。スフィンクスも使用してこのフォーマットを解析することができることに留意されたいナポレオンスフィンクス1.3とともにパッケージ来る拡張を、(これもと互換性のある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に関する包括的な例を示します


20
docstringsを読んでいるすべての人間のために
Waylon Flinn

1
Google Pythonスタイルガイドのリンクを更新
confused00

@ confused00私のメソッドがオブジェクトの配列を返すことをどのように文書化できますか?
Cito 2017年

1
今私は混乱しています!argsまたはparams?stackoverflow.com/questions/1788923/parameter-vs-argument
shuva 2018

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 '')
    """

17
PEP257は、引数部分の実際のフォーマットについては何も教えていません。それは書かれるべきであると述べ、例を示します。しかし、これは単なる例です。したがって、PEP257を壊さず、sphinxで解析できるフォーマットを使用しているため、Sphinxの規則を使用することを決定的にお勧めします。
vaab 2013

7
上記の最初のドキュメントは醜く、人間にとって冗長な情報がたくさんありますが。ソースコードを最初に解析せずに読みやすくする規則を使用したい
confused00

弊社のサイトを使用することにより、あなたは弊社のクッキーポリシーおよびプライバシーポリシーを読み、理解したものとみなされます。
Licensed under cc by-sa 3.0 with attribution required.