Pythonドキュメントコメント

Pythonのドキュメントコメント(Docstrings)の書き方です。
どうも、派閥？流派？があるようです。

Short Summary：簡単な1行説明。名前とか

NumPyスタイル.py

def add(a, b):
   """The sum of two numbers.

   """

Googleスタイル.py

def add(a, b):
   """The sum of two numbers.

   """

Extended Summary: 複数行の詳細な概要

NumPyスタイル.py

def add(a, b):
   """The sum of two numbers.

   (Extended Summary)
   """

Googleスタイル.py

def add(a, b):
   """The sum of two numbers.

   (Extended Summary)
   """

Parameters: 関数の引数

NumPyスタイル.py

"""
Parameters
----------
x : type
    Description of parameter `x`.
y
    Description of parameter `y` (with type not specified)
"""

Googleスタイル.py

"""
Args:
  x (type): Description of parameter `x`.
  y: Description of parameter `y` (with type not specified)
"""

Returns: 関数の返り値

NumPyスタイル.py

"""
Returns
-------
int
    Description of anonymous integer return value.
"""

NumPyスタイル.py

"""
Returns
-------
err_code : int
    Non-zero value indicates error code, or zero on success.
err_msg : str or None
    Human readable error message, or None on success.
"""

Googleスタイル.py

"""
Returns:
  int: Description of anonymous integer return value.
"""

Raises: 例外

NumPyスタイル.py

"""
Raises
------
LinAlgException
    If the matrix is not numerically invertible.
"""

Googleスタイル.py

"""
Raises:
  LinAlgException: If the matrix is not numerically invertible.
"""

Notes: 備考。追加の説明。LaTeXも使える。

NumPyスタイル.py

"""
Notes
----------
The FFT is a fast implementation of the discrete Fourier transform:
.. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
"""

Googleスタイル.py

"""
Note:
  The FFT is a fast implementation of the discrete Fourier transform:
  .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n}
"""

Examples: 使用例

NumPyスタイル.py

"""
Examples
----------
>>> np.add(1, 2)
3
"""

Googleスタイル.py

"""
Example:
  >>> np.add(1, 2)
  3
"""

Attributes: クラスの属性

NumPyスタイル.py

"""
Attributes
----------
x : float
    The X coordinate.
y : float
    The Y coordinate.
"""

Googleスタイル.py

"""
Attributes:
  x (float): The X coordinate.
  y (float): The Y coordinate.
"""

Methods: クラスのメソッド

NumPyスタイル.py

"""
Methods
-------
colorspace(c='rgb')
    Represent the photo in the given colorspace.
gamma(n=1.0)
    Change the photo's gamma exposure.
"""

Googleスタイル.py

# なし

Pythonドキュメントコメント

Short Summary：簡単な1行説明。名前とか

Extended Summary: 複数行の詳細な概要

Parameters: 関数の引数

Returns: 関数の返り値

Raises: 例外

See Also: 関連項目

Notes: 備考。追加の説明。LaTeXも使える。

Examples: 使用例

Attributes: クラスの属性

Methods: クラスのメソッド