Pythonコメントの書式｜単複コメントとDocstring書式と使い方
Pythonコメントの書式｜単複コメントとDocstring書式と使い方
Pythonの単行複数行コメントの書き方、Docstringの書式と使い方、全てのタグを解説。Docstringタグの使用例をサンプルコードで分かりやすく解説。
Pythonコメント Docstring 目次
Pythonのコメント
Pythonのコメントは、#（単行） のみである。Java、PHP、Go のような /* */（複数行）のコメントはない。
複数行のコメントがないのは非常に不便なので、便宜的に複数行文字列で使用する """ """ (トリプルクォート) を、複数行のコメントに使用している。
※ 注記 """ を使うときは、前後のプログラムと行頭のスペース（インデント）を合わせる必要がある。ズレているとエラーになる。
- # は # から改行までをコメントとして認識する。
記述 例 # コメントを書く→ コードをクリップボードにコピーする
- """ """ (トリプルクォート) は 1つ目の """ をコメント開始タグ、 2つ目の """ をコメント終了タグとして認識し、タグの内側をコメントとして認識する。
単行記述 例 """ コメントを書く """ 複数行記述 例 """ コメントを書く hogehoge bonobono shimarisu """→ コードをクリップボードにコピーする
Google Colab や多くのエディタでは、範囲を選択して Ctrl + /（Macは Cmd + /）を押すと、一気に # を付けたり消したりできる。このノロマが・・・って思われたくなかったら使え！
他言語のコメント書式は コメントの言語別書式機能比較 を参照。
Python Docstringのコメント
""" """ は Docstring（ドックストリング） と呼ばれ、関数やクラスの説明、引数の型、戻り値などの説明を記述するために使う。
これを書くことで、HTML形式のAPIドキュメントを生成したり、開発ツール（VSCodeやPyCharmなど）上でマウスを置いた時に説明文や型ヒントがポップアップ表示されるようになる。
書式
Docstringには、Googleスタイル、NumPyスタイル、reStructuredText（標準）などの書き方がある。
用途に合わせてプロジェクト内で統一して記述するのが一般的。
def hoge_func(arg1: int) -> bool:
"""関数の説明。
Args:
arg1 (int): 引数の説明
Returns:
bool: 戻り値の説明
"""
return True
→ コードをクリップボードにコピーする
基本コマンド (pydoc)
Python標準の pydoc を使い、ブラウザで確認したりHTMLを出力したりできる。
-p [ポート番号]：ローカルサーバーを起動し、ブラウザでドキュメントを閲覧する。
-w [モジュール名]：指定したモジュールのHTMLファイルをカレントディレクトリに出力する。
python -m pydoc -p 8080
python -m pydoc -w my_script→ コードをクリップボードにコピーする
ドキュメント生成ツール（Sphinx）
Pythonで最も一般的なツール。インストール後、プロジェクトのルートディレクトリで初期設定を行い実行する。
sphinx-quickstart：対話形式で設定ファイル（conf.pyなど）を作成する。
sphinx-build：ソースコードからHTMLドキュメントを生成する。
# 初期設定
sphinx-quickstart docs
# HTML生成（docsディレクトリに出力）
sphinx-build -b html source docs
→ コードをクリップボードにコピーする
簡易ツール (pdoc)
設定不要で、コマンド一つで素早くHTMLドキュメントを生成できるツール。
-o [出力先]：生成されたHTML群を出力するディレクトリを指定する。
# インストール
pip install pdoc
# カレントディレクトリの全モジュールを対象に生成
pdoc -o ./docs .
# ディレクトリ my_package の全モジュールを対象に生成
pdoc -o ./docs my_package/→ コードをクリップボードにコピーする
他言語のコメント書式は コメントの言語別書式機能比較 を参照。
