Pythonのドキュメントコメント(Docstrings)の書き方、何やら流派があるらしい。。
NumPyスタイルを調べてみたので、その時の備忘録。
- reStructuredText（reST）スタイル
- NumPyスタイル
- Googleスタイル
NumPyスタイルの例
Short Summary：簡単な1行説明。名前とか
def add(a, b): """The sum of two numbers. """
Extended Summary: 複数行の詳細な概要
def add(a, b): """The sum of two numbers. (Extended Summary) """
Parameters: 関数の引数
""" Parameters ---------- x : type Description of parameter `x`. y Description of parameter `y` (with type not specified) """
Returns: 関数の返り値
""" Returns ------- int Description of anonymous integer return value. """
""" 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. """
Raises: 例外
""" Raises ------ LinAlgException If the matrix is not numerically invertible. """
See Also: 関連項目
""" See Also -------- average : Weighted average """
Notes: 備考。追加の説明。LaTeXも使える。
""" Notes ---------- The FFT is a fast implementation of the discrete Fourier transform: .. math:: X(e^{j\omega } ) = x(n)e^{ - j\omega n} """
Examples: 使用例
""" Examples ---------- >>> np.add(1, 2) 3 """
Attributes: クラスの属性
""" Attributes ---------- x : float The X coordinate. y : float The Y coordinate. """
Methods: クラスのメソッド
""" Methods ------- colorspace(c='rgb') Represent the photo in the given colorspace. gamma(n=1.0) Change the photo's gamma exposure. """
Googleスタイル編はこちら
wannabe-jellyfish.hatenablog.com
