変数に対するdocstringの書き方

Question

現在、docstringの書き方を勉強しております。
クラスや関数に対して付与するdocstringの書き方は、検索すると出てきますが、変数に対してはどのように付与すればよいのでしょうか？

変数がどのような変数なのかを明示するために、変数に対してコメント行を付与しており、そのようなコメント行をdocstringへと書き換えたいと思っています。

def function():
    # これは変数です
    a = "AAA"

例えば、上記のような関数がある場合、

def function():
"""
これは関数です。
"""
    a = "AAA"
    """
    これは変数です。
    """

のような書き方をすることになるのでしょうか？
加えて、あるひとまとまりの変数の一群に対してそのまとまりを説明するコメントを付与する場合はどうなるのでしょうか？

def function():
    # 変数の中身は文字列です。
    a = "AAA"
    b = "BBB"
    c = "CCC"

　　# 変数の中身は数値です。
    X = 1
    Y = 2
    Z = 3

以上のような関数の場合、docstringは、

def function():
"""
これは関数です。
"""
    a = "AAA"
    b = "BBB"
    c = "CCC"
    """
    変数の中身は文字列です。
    """
    X = 1
    Y = 2
    Z = 3
    """
    変数の中身は数値です。
　　"""

のような書き方をすることになるのでしょうか？

Answer 1

docstringは「外から見るために」書くものです。

必要なのは引数と返り値、あと属性値や副作用の情報ですね。

関数の内部でだけ使う変数については、docstringに記述する必要はありません（というか書くべきではありません）。通常のコメントで十分です。

Comments

[Ykkykk]

ご回答いただきありがとうございます。
docstringで書く部分と通常のコメント行を混ぜて書いてもよいのですね。

クラスのメソッドにある変数で他のメソッドでも使うような場合はどうなるのでしょうか？？

[hayataka2049]

まずはっきりさせておきますが、docstringは「クラス、関数、モジュールの最初の式である文字列リテラル」です。
https://docs.python.jp/3/glossary.html#term-docstring
なので変数の前後に"""で囲ったリテラルを書いたとしても、それはただのコメントであってdocstringにはなりません。

[hayataka2049]

＞クラスのメソッドにある変数で他のメソッドでも使うような場合
クラス変数やインスタンス変数のことでしょうか。
「他のメソッドでも使う」がオブジェクトの内部で状態を保持するためだけに使う、ということであれば、記載する必要は全くありません。
ただし、属性値としてユーザー（自分以外の、自分の書いたクラスや関数を単に使うだけの人。ライブラリを書いているなら単純にそのユーザーですし、あるいは何らかのプロジェクトのコードなら、共同開発者などが該当します）がアクセスすることも意図するのであれば、クラスの属性として書いておいて良いでしょう。というか書いておいてください。
要するに、ユーザーがその関数・クラス・メソッドを使う上で必要な情報を書けば良いのであって、「変数の説明のコメントをdocstringにしたい」という発想がそもそも間違っています。

[Ykkykk]

詳細にお教えいただきありがとうございます。
納得できました。
ありがとうございました！