9.基本編-Docstrings(Python)※引用過ぎるので理解したら書く

PythonのDocstrings

Googleスタイル形式でのPython Docstringの内容が、こちらに綺麗にまとまっている。

サンプル

【全般】
・ソースコードの一番始めに記載すること(importより前に記載する)
・コメントを複数行のコメントブロック「“”“」で囲む
・コメント開始の「”““」の右隣にタイトルを記載する
・コメントを閉じる「””“」は単独の行として記述する
・対象となるのは、 モジュール、クラス、関数の3つ

【セクション】
・Attributes, Args、Returns、Yieds、Raises、Examples、Note、Todoという用途別に定義されたセクションがある。

Attributes:
    属性の名前 (属性の型): 属性の説明
    属性の名前 (:obj:`属性の型`): 属性の説明.

Args:
    引数の名前 (引数の型): 引数の説明
    引数の名前 (:obj:`引数の型`, optional): 引数の説明.
    
Returns:
    戻り値の型: 戻り値の説明 (例 : True なら成功, False なら失敗.)
    
Yields:
    戻り値の型: 戻り値についての説明

Raises:
    例外の名前: 例外の説明 (例 : 引数が指定されていない場合に発生 )
    
Examples:
    関数の使い方について記載

    >>> print_test ("test", "message")
        test message
        
Note:
   注意事項などを記載
   
Todo:
    TODOリストを記載
    * conf.pyの``sphinx.ext.todo`` を有効にしないと使用できない
    * conf.pyの``todo_include_todos = True``にしないと表示されない