【Python】VScodeではブロックコメントでマークダウン記法ができる
2023 年 7 月 31 日 by tomokiy概要
Pythonのブロックコメントをマークダウン記法で記述すると、VScodeのコードヒントを表示した時にいい感じに表示されます。
やり方
パッケージのコメント
上記のように自作パッケージにカーソルを当てると、コメントが表示されます。
"""
## 自作パッケージ
## 概要
自作パッケージ概要
## クラス一覧
### `Param`
Paramクラスの説明
### `Log`
Logクラスの説明
"""
クラスのコメント
クラスのコメントです。コンストラクタを記述する際にも表示されるので、分かりやすいですね。 以下はこのコメントを書いている部分です。
class Log(Base):
"""
## ログクラス
ログの設定と出力を行うクラスです。
### 引数
- `log_path` : ログのパス
- `level` : ログの出力レベル
- `rotation` : ローテーション `"M"`:月ごと、`"D"`:日ごと\\
ログファイル名に`.yyyy-mm-dd`が付加されます。
- `archive_count` : ログファイルアーカイブ数\\
ログファイルのディレクトリに、指定した数を超えたログファイルがある場合、\\
日付の古いものから削除されます。`0`の場合、削除されません。\\
ローテーションを指定した場合のみ設定が有効になります。
"""
@method
def __init__(self,log_path:str,level:int=logging.DEBUG,rotation:str=None,archive_count:int=0) -> None:
super().__init__()
# 省略
メソッドのコメント
メソッドのコメントです。メソッドを記述する際にも表示されます。 以下はこのコメントを書いている部分です。
def execute_query(self,sql:str,parameter:tuple=None) -> list:
"""
## SQL実行
SQL（クエリ）を実行します。\\
トランザクションが開始されていない場合は開始します。
### 引数
- `sql` : SQL文
- `parameter` : パラメータ
### 戻り値
- SQL実行結果
"""
# 省略
コメントテンプレート
クラス
クラスコメントはclass クラス名の下に書きます。 コンストラクタの下に書いても表示されないので、コンストラクタの下にコメントは不要です。
"""
## クラス名
クラス説明
### 引数
- `arg1` : 引数1
- `arg2` : 引数2
### 戻り値
- 戻り値
"""
メソッド
メソッドコメントはdef メソッド名():の下に書きます。
"""
## メソッド名
メソッド説明
### 引数
- `arg1` : 引数1
- `arg2` : 引数2
### 戻り値
- 戻り値
"""
補足
- 改行するだけでは改行されない
def test():
"""
## メソッド名
メソッド説明
改行
### 引数
- `arg1` : 引数1
- `arg2` : 引数2
### 戻り値
- 戻り値
"""
\\で改行する
def test():
"""
## メソッド名
メソッド説明\\
改行
### 引数
- `arg1` : 引数1
- `arg2` : 引数2
### 戻り値
- 戻り値
"""
\nは段落が変わる
def test():
"""
## メソッド名
メソッド説明\n
改行
### 引数
- `arg1` : 引数1
- `arg2` : 引数2
### 戻り値
- 戻り値
"""
- 箇条書きはもちろん、番号でもOK
def test():
"""
## メソッド名
メソッド説明
### 引数
1. `arg1` : 引数1
2. `arg2` : 引数2
### 戻り値
- 戻り値
"""
- 表も作れるが、枠線が無いので分かりずらい
def test():
"""
## メソッド名
メソッド説明
| key | value |
| --- | --- |
| a | aaaaa |
| b | bbbbb |
### 引数
1. `arg1` : 引数1
2. `arg2` : 引数2
### 戻り値
- 戻り値
"""
- 引用はできない
def test():
"""
## メソッド名
メソッド説明
> aaaaaa
### 引数
1. `arg1` : 引数1
2. `arg2` : 引数2
### 戻り値
- 戻り値
"""
- コードブロックは色文字で分かりやすい ごめんなさい。コードブロック内にコードブロックを書けないので、
（コードブロック）と書いているところは```に置き換えて考えてください。
def test():
"""
## メソッド名
メソッド説明
（コードブロック）
def test():
a = 1
（コードブロック）
### 引数
1. `arg1` : 引数1
2. `arg2` : 引数2
### 戻り値
- 戻り値
"""
タグ: Python
