Pythonで関数やクラスのドキュメンテーションを行うdocstringには、いくつかの一般的なフォーマットがあります。これらのdocstringは、コード内で説明を記述する方法であり、ツールを使ってHTMLなどに変換することも可能です。以下では、Pythonでよく使われる主なdocstringフォーマットとその特徴を紹介します。

Epydoc（Epytext形式）

Epydocは、Pythonのドキュメント生成ツールとしてかつて広く使われたもので、その形式はJavaのjavadocスタイルに似ています。この形式では、@paramや@returnなどのタグを使ってパラメータや戻り値を説明します。例としては次のようになります。

"""
This is a javadoc style.
@param param1: this is a first param
@param param2: this is a second param
@return: this is a description of what is returned
@raise KeyError: raises an exception
"""

現在では、reSTやGoogleスタイルの方がよく使われますが、Epytextは今も一部で利用されています。

reST（reStructuredText）

最も普及しているフォーマットの一つがreStructuredText（reST）形式で、特にSphinxを使用する場合に推奨されます。JetBrainsのPyCharmや他のIDEでも、この形式がデフォルトで使われることが多いです。:を用いた明確なタグで説明が書かれます。

"""
This is a reST style.
:param param1: this is a first param
:param param2: this is a second param
:returns: this is a description of what is returned
:raises KeyError: raises an exception
"""

Sphinxでのドキュメント生成時には、この形式が自動的にHTMLやPDFに変換されます。

Googleスタイル

Googleスタイルは、簡潔で読みやすいdocstring形式として人気があります。この形式はSphinxのNapoleonプラグインを利用して解析できます。Pythonコードにおいては次のように書かれます。

"""
This is an example of Google style.
Args:
    param1: This is the first param.
    param2: This is a second param.
Returns:
    This is a description of what is returned.
Raises:
    KeyError: Raises an exception.
"""

Googleスタイルは特に開発者にとって分かりやすく、効率的な記述が可能です。

Numpydoc

Numpydocは、科学計算やデータ解析を扱うライブラリで広く使われるdocstringフォーマットです。この形式はGoogleスタイルに似ていますが、さらに詳しいパラメータの説明やデータ型の指定が含まれています。

"""
My numpydoc description of a kind
of very exhaustive numpydoc format docstring.
Parameters
----------
first : array_like
    the 1st param name `first`
second :
    the 2nd param
third : {'value', 'other'}, optional
    the 3rd param, by default 'value'
Returns
-------
string
    a value in a string
Raises
------
KeyError
    when a key error
OtherError
    when another error occurs
"""

Numpydocは、複雑なデータ構造や科学的な関数を扱う場合に特に有効で、NumPyやSciPyなどで標準的に使用されています。

まとめ

Pythonのdocstringには複数のフォーマットがありますが、最も一般的なのはreST形式です。その他にもGoogleスタイルやNumpydocが特定の用途で使われており、コードの読みやすさやドキュメンテーションの自動化に役立ちます。どの形式を使用するかはプロジェクトのニーズやチームの慣習によりますが、一貫性を保つことが重要です。