web-dev-qa-db-ja.com

Pythonドキュメントにjavadocを使用する

私は現在Pythonで始まり、PHPの強力なバックグラウンドを持っています。PHPでは、javadocをドキュメントテンプレートとして使用する習慣を取りました。

javadocがPythonの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)
pythondocumentationjavadocdocstring
157
JF Dion

reStructuredText （「reST」としても知られる）形式を見てください。これはプレーンテキスト/ docstringマークアップ形式であり、おそらくPythonの世界で最も人気があります。そして、あなたは確かに Sphinx 、reStructuredTextからドキュメントを生成するツール（例えば、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
"""
224
Steven

Google Python St​​yle Guide に従ってください。 Sphinxは Napolean 拡張を使用してこの形式を解析することもできます。これはSphinx 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の包括的な例 here 。

73
confused00

pythonドキュメンテーション文字列の標準は Python Enhancement Proposal 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 '')
    """
25
srgerg

Documenting Python をご覧ください。「Pythonのドキュメントの著者および潜在的な著者を対象としています」ページです。

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

1
David Cain