1. ホーム
  2. python

[解決済み] Pythonのドキュメントにjavadocを使う [終了しました]

2022-04-23 14:46:21

質問

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

と思っていたのですが javadoc は、その場所を docstring のドキュメントをPythonで作成します。 ここで確立された規約や公式ギルドラインは何ですか?

例えば、このようなことは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)

解決方法は?

をご覧ください。 reStructuredText (別名 "reST") フォーマットはプレーンテキスト/docstring マークアップフォーマットで、おそらく Python の世界で最も人気のあるフォーマットでしょう。そして、あなたは確かに スフィンクス reStructuredTextからドキュメントを生成するツールです(例えば、Pythonのドキュメント自体に使用されています)。Sphinxには、コードの中のdocstringからドキュメントを抽出する機能があります( sphinx.ext.autodoc を認識します。 フィールドリスト は、一定の規則に従っています。これはおそらく最も一般的な方法になっている(あるいはなりつつある)でしょう。

例としては、次のようなものが考えられます。

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