Python PEP257 docstringの書き方

docstringはモジュール、関数、クラス、に追加できる説明文です。
3重クォートをdefのすぐ下の行に入れます。3重クォートは、「""" 」でも 「'''」 でもどちらでも使えます。#でのコメントアウトは使えません。

定義後は、オブジェクト名.__doc__　でアクセスできます。

1行説明文を書く

def foo():
    """This is a test."""
    x = 1
    ....

拡張を見越して1行でも3重クォートで書くほうがよいとされています。
文は完全な文で書きます(大文字始まり、ピリオドあり)。コード本文は閉じる"""の次の行から空白行なしで書き始めます。

1行めの場所

"""
something...
"""

と書くと、一行目は上側の""" の右側(この例では空白)になり、__doc__の結果は\nから始まります。それで問題なければ大丈夫ですが\n始まりが嫌なときは

"""something...
"""

と書きます。

最初の一行のあと、1行スペースを入れる

def bar():
    """This is test.
    This test is for ....
    and ...
    ...
    """

パラメータを書くときは1行に1つ

def baz(a, b):
    """This is test.
    Parameters:
    a: test param1, text
    b: test param2, int
    ...
    """

docstring欄にコメントアウトも入れられる

def df_init():
    '''初期化 読み出し, index追加
  
    # df = pd.read_csv('./data/all_data.csv')
    # df['index'] = range(len(df))
    '''
    ....

と定義してから

df_init?

とやって確認すると、#がDocstring内にあることが確認できます。

Signature: df_data_all_init()
Docstring:
初期化 読み出し, index追加
# df = pd.read_csv('./data/all_data.csv')
# df['index'] = range(len(df))
File:      ~/anaconda3/...
Type:      function