Pythonのドキュメントコメントの書き方(Googleスタイル編)

Pythonのドキュメントコメント(Docstrings)の書き方、何やら流派があるらしい。。
Googleスタイルを調べてみたので、その時の備忘録。

1. reStructuredText（reST）スタイル
2. NumPyスタイル
   • numpydoc – Numpy’s Sphinx extensions — numpydoc v0.9.dev0 Manual
   • NumPyスタイルPython Docstringsの例 — Sphinx 1.5.6 ドキュメント
3. Googleスタイル
   • styleguide/pyguide.md at gh-pages · google/styleguide · GitHub
   • GoogleスタイルのPython Docstringsの例 — Sphinx 1.5.6 ドキュメント

Googleスタイルの例

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: 関数の引数

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

Returns: 関数の返り値

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

Raises: 例外

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

See Also: 関連項目

なし

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

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

Examples: 使用例

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

Attributes: クラスの属性

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

Methods: クラスのメソッド

なし

NumPyスタイル編はこちら

wannabe-jellyfish.hatenablog.com

参考になる書籍

基礎から学ぶ Django

Python Django 超入門

現場で使える Django の教科書《基礎編》

現場で使える Django の教科書《実践編》

参考にしたサイト様

• [Python]可読性を上げるための、docstringの書き方を学ぶ（NumPyスタイル） - Qiita
• Pythonのdocstring（ドキュメンテーション文字列）の書き方 | note.nkmk.me