この記事では、Pythonのドキュメンテーション文字列の使い方を解説します。
ドキュメンテーション文字列は、関数やクラスなどに目的や機能を記述するためのものです。また、ドキュメンテーション文字列を用いてテストを行うこともできます。
それでは、ドキュメンテーション文字列の使い方を見ていきましょう❗️
ドキュメンテーション文字列とは？
ドキュメンテーション文字列とは、クラスや関数、モジュールの説明を記述するための機能です。docstringとも呼ばれます。
自作した関数やクラス、モジュールなどにドキュメンテーション文字列を書いておくことで他の人が使うときや自分が使うときなどの理解の助けとなります。
また、ドキュメンテーション文字列に型を宣言しておくことで IDE で型チェックがされたり、Sphinxなどのツールを使うことでドキュメントを自動生成することもできます。
では、ドキュメンテーション文字列の書き方を見ていきましょう！
ドキュメンテーション文字列の書き方
ドキュメンテーション文字列は、クラスや関数の定義の先頭に「複数行文字列」を記述することで定義することができます。
複数行文字列は、クォーテーション3つで囲むことで表現できます。
def func():
"""
"""次に中に書く内容について見ていきましょう！
目的や機能
まず、「目的」や「機能」を１行で簡潔に記述します。
書き方は、「大文字」で始まり「ピリオド(.)」で終わらせる必要があります。日本語でも記述可能ですが非推奨です。
def func():
"""目的や機能
"""簡単な関数ならこの１行を書くだけで十分です。
規約や副作用
次に、3行目から呼び出し規約や副作用について書きます。この項目は複数行に渡って記述しても構いません。
def func(num, s):
"""目的や機能
呼び出し規約や副作用
"""特に書くことが無いなら省略しても問題ありません。
引数や戻り値の概要と型
最後に引数や戻り値の概要と型を記述します。
書き方(スタイル)がいくつかあるので1つずつ見ていきましょう！
reStructuredText
一番標準的なスタイルです。
def func(引数1, 引数2):
"""目的や機能
呼び出し規約や副作用
:param 引数1: 引数1の概要
:type 引数1: 引数1の型
:param 引数2: 引数2の概要
:type 引数2: 引数2の型
:rtype: 戻り値のかた
:return: 戻り値の概要
"""型は TypeHint で書いて概要はドキュメンテーション文字列で書くことで少しだけスッキリとさせることができます。
def func(引数1: int, 引数2: str) -> float:
"""目的や機能
呼び出し規約や副作用
:param 引数1: 引数1の概要
:param 引数2: 引数2の概要
:return: 戻り値の概要
"""NumPyスタイル
縦に色々記述できるスタイル。
def func(引数1, 引数2):
"""目的や機能
呼び出し規約や副作用
Parameters
----------
引数1 : 型
引数1の概要
引数2 : 型
引数2の概要
Returns
-------
戻り値の型
戻り値の概要
"""他にもクラスに Attributes を記述したり Examples で使い方の例を記述したりもできます。
Googleスタイル
とても見やすいスタイル。
def func(引数1, 引数2):
"""目的や機能
呼び出し規約や副作用
Args:
引数1 (型): 引数1の概要
引数2 (型): 引数2の概要
Returns:
戻り値の型: 戻り値の概要
"""ドキュメントを作ったり、TypeHint を書く場合は「reStructuredText」を使い、それ以外の場合は自分の好きなスタイルを使って問題ありません。
モジュールやクラスのドキュメンテーション文字列
モジュールやクラスにdocstringを書くときは、１行目に簡潔な概要を書いて３行目から詳細を書いていきます。
"""モジュールの概要
詳細
"""
class MyCls:
"""クラスの概要
詳細
"""例として、functoolsモジュールのdocstringを見てみます。
functools.py
"""functools.py - Tools for working with functions and callable objects
"""さらに、partialmethodクラスのドキュメントも見てみましょう！
class partialmethod(object):
"""Method descriptor with partial application of the given arguments
and keywords.
Supports wrapping existing descriptors and handles non-descriptor
callables as instance methods.
"""ドキュメンテーション文字列の確認
ドキュメンテーション文字列は、__doc__属性に文字列として格納されます。
def func(num: int, s: str) -> float:
"""簡潔な概要
:param num: numの概要
:param s: sの概要
:return: 戻り値の説明
"""
print(func.__doc__)実行結果
簡潔な概要
:param num: numの概要
:param s: sの概要
:return: 戻り値の説明もちろん、組み込み関数などにも使えます。
print(abs.__doc__)
# Return the absolute value of the argument.また、ドキュメンテーション文字列を書いた関数などをhelp()関数に渡すことでドキュメントを読むことができる。
def func(num: int, s: str) -> float:
"""簡潔な概要
:param num: numの概要
:param s: sの概要
:return: 戻り値の説明
"""
help(func)実行結果
Help on function func in module __main__:
func(num: int, s: str) -> float
簡潔な概要
:param num: numの概要
:param s: sの概要
:return: 戻り値の説明
(END)まとめ
この記事では、Pythonのドキュメンテーション文字列について解説しました。
自作したクラスや関数にドキュメンテーション文字列を書いて誰もが使いやすいコードを作成しましょう。使い方がイマイチわからない関数やクラスがあったらドキュメンテーション文字列を見て確認することができます。
また、ドキュメンテーション文字列を用いたテストは以下の記事を参考にして下さい。
docstringを使って関数をテストする方法を解説【doctest】
それでは今回の内容はここまでです。ではまたどこかで〜( ・∀・)ﾉ
