docstringの書き方 #備忘録

# はじめに
docstringについて忘れないための備忘録です。

# docstringとは
関数やクラス、モジュール全体の説明を行うためのコメントのことです。
'''又は"""で囲まれた範囲に説明を記載します。
PEP 257（Python Enhancement Proposal 257）にdocstringの書き方に関するガイドラインが示されています。
help()関数でdocstringの内容を参照することができます。

# 書き方のスタイルについて
書き方に主に3つあります。
- Googleスタイル
Googleが推奨するスタイルで、簡潔かつ視覚的に分かりやすいのが特徴。

- Numpyスタイル
科学技術分野でよく使われるNumPyライブラリで採用されているスタイル。説明が詳細でデータ型の記述が明確。
 
- reStructuredTextスタイル
Sphinxを使ってドキュメントを生成する際に適しているスタイルです。Pythonコミュニティで広く支持されている。

## Googleスタイル
```text
def example_function(param1, param2, flag=True):
    """
    Googleスタイルのdocstringの書き方を説明する関数です。

    この関数は、Googleスタイルのdocstringの各セクションの構造を示します。
    引数、戻り値、例外、使用例などを記述します。

    Args:
        param1 (int): 最初の引数で、整数を指定してください。
        param2 (str): 2番目の引数で、文字列を指定してください。
        flag (bool, optional): オプションの引数で、デフォルトはTrueです。

    Returns:
        str: 入力された値を基にした説明文を返します。

    Raises:
        ValueError: param1が負の数の場合に発生します。
        TypeError: param2が文字列ではない場合に発生します。

    Examples:
        >>> example_function(5, "Python")
        '入力値は5とPythonです。'
        >>> example_function(-1, "Test")
        ValueError: param1は0以上である必要があります。
    """
    if not isinstance(param1, int):
        raise TypeError("param1は整数である必要があります。")
    if not isinstance(param2, str):
        raise TypeError("param2は文字列である必要があります。")
    if param1 < 0:
        raise ValueError("param1は0以上である必要があります。")

    return f"入力値は{param1}と{param2}です。"
```

# Numpyスタイル
```text
def example_function(param1, param2, flag=True):
    """
    Numpyスタイルのdocstringの書き方を説明する関数です。

    この関数は、Numpyスタイルのdocstringの各セクションの構造を示します。
    引数、戻り値、例外、使用例などを記述します。

    Parameters
    ----------
    param1 : int
        最初の引数で、整数を指定してください。
    param2 : str
        2番目の引数で、文字列を指定してください。
    flag : bool, optional
        オプションの引数で、デフォルトはTrueです。

    Returns
    -------
    str
        入力された値を基にした説明文を返します。

    Raises
    ------
    ValueError
        param1が負の数の場合に発生します。
    TypeError
        param2が文字列ではない場合に発生します。

    Examples
    --------
    >>> example_function(5, "Python")
    '入力値は5とPythonです。'
    >>> example_function(-1, "Test")
    Traceback (most recent call last):
    ...
    ValueError: param1は0以上である必要があります。
    """
    if not isinstance(param1, int):
        raise TypeError("param1は整数である必要があります。")
    if not isinstance(param2, str):
        raise TypeError("param2は文字列である必要があります。")
    if param1 < 0:
        raise ValueError("param1は0以上である必要があります。")

    return f"入力値は{param1}と{param2}です。"
```

# reStructuredTextスタイル
```
def example_function(param1, param2, flag=True):
    """
    Googleスタイルのdocstringの書き方を説明する関数です。

    この関数は、Googleスタイルのdocstringの各セクションの構造を示します。
    引数、戻り値、例外、使用例などを記述します。

    :param param1: 最初の引数で、整数を指定してください。
    :type param1: int
    :param param2: 2番目の引数で、文字列を指定してください。
    :type param2: str
    :param flag: オプションの引数で、デフォルトはTrueです。
    :type flag: bool, optional
    :return: 入力された値を基にした説明文を返します。
    :rtype: str
    :raises ValueError: param1が負の数の場合に発生します。
    :raises TypeError: param2が文字列ではない場合に発生します。

    :Example:

    >>> example_function(5, "Python")
    '入力値は5とPythonです。'
    >>> example_function(-1, "Test")
    Traceback (most recent call last):
    ...
    ValueError: param1は0以上である必要があります。
    """
    if not isinstance(param1, int):
        raise TypeError("param1は整数である必要があります。")
    if not isinstance(param2, str):
        raise TypeError("param2は文字列である必要があります。")
    if param1 < 0:
        raise ValueError("param1は0以上である必要があります。")

    return f"入力値は{param1}と{param2}です。"
```

# おわりに
クラスやモジュールについての書き方については今度かければと思います。