この記事では、Pythonのドキュメンテーション文字列の使い方を解説します。ドキュメンテーション文字列を定義することで、関数やクラスなどに目的や機能がわかるように説明文を記述することができます。また、ドキュメンテーション文字列を用いてテストを行うこともできます。それでは、ドキュメンテーション文字列の使い方を見ていきましょう❗️
ドキュメンテーション文字列とは？
ドキュメンテーション文字列とは、クラスや関数、モジュールの説明を記述するための機能です。docstringとも呼ばれます。
自作した関数やクラス、モジュールなどにドキュメンテーション文字列を書いておくことで他の人が使うときや自分が使うときなどの助けとなります。
また、ドキュメンテーション文字列に型を宣言しておくことでIDEで型チェックがされるようにできたり、Sphinxなどのツールを使うことでドキュメントを自動生成することもできます。
ドキュメンテーション文字列の書き方
ドキュメンテーション文字列はクラスや関数の定義の先頭に複数行文字列を記述することで定義することができます。
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のドキュメンテーション文字列について解説しました。
自作したクラスや関数にドキュメンテーション文字列を書いて誰もが使いやすいコードを作成しましょう。使い方がイマイチわからない関数やクラスがあったらドキュメンテーション文字列を見て確認することができます。
また、ドキュメンテーション文字列を用いたテストは以下の記事を参考にして下さい。
それでは今回の内容はここまでです。ではまたどこかで〜( ・∀・)ﾉ
