Rust PyO3ドキュメンテーションコメントメモ

Rustのpyo3のPython用ドキュメンテーションコメント（Docstring）のメモ。

概要

PyO3を使って定義されたクラスやメソッドに「///」を使ったRustのドキュメンテーションコメントを書いておくと、ビルド後にPythonのDocstringとして扱われる。

すなわち、Pythonオブジェクトの__doc__に格納され、Pythonのhelp関数で参照することが出来る。

ただし、RustとPythonではドキュメンテーションコメントの書き方（構文・作法）が異なる。
例えば引数や戻り値は、Rustでは「# Parameters」「# Returns」でセクションを作るが、Python（Google style）は「Args:」「Returns:」で書く。

PyO3アプリケーションはPythonのライブラリーとして提供するから、APIドキュメントもPythonとして提供するだろう。
なので、ドキュメンテーションコメントはPython形式で書いておく。

PyO3アプリケーションにおけるPython Docstringは、Rustのドキュメンテーションコメントと合わせて、以下のような形で記述する。

/// セクション:
///     説明

「///」で始めることにより、Rustのドキュメンテーションコメントとする。
その後、PythonのDocstringを書く。すなわち、セクション名の末尾にコロン「:」を付けて改行し、次の行の冒頭にインデントを入れる。

PythonのDocstringはPythonの文法に似ている。たぶん意図的に合わせてあるのだろう。

pdoc3を使うと、ドキュメンテーションコメントからPythonのAPIのHTMLファイルを生成することが出来る。

また、pyo3-stub-genによって生成できる型スタブファイルにも、ドキュメンテーションコメントが転記される。

全般的な記法

説明文の中でバッククォート「`」で囲んだ文字列は、コード文字列として修飾される。

また、pdoc3でHTMLファイルを生成した際、その文字列がクラス名・関数名・メソッド名と合致する場合は、それへのリンクになる。

/// 関数へのリンクの例 `my_function()`
/// クラスへのリンクの例 `MyClass`
/// メソッドへのリンクの例 `MyClass.my_method()`

pdoc3で生成されるHTMLファイルの中で改行したい場合は、行末に空白を2つ入れる。

/// 説明文1  ←行末に空白を2つ入れる
/// 説明文2

モジュール

モジュールのPython Docstringの例。

/// モジュールの例.
#[pymodule]
mod example_pyo3 {
    〜
}

※Rustモジュールを不可視にした場合は、ここのドキュメンテーションコメントは出なくなる。（python/**/__init__.pyにDocstringを書く）

クラス

クラスのPython Docstringの例。

/// サンプルクラス.
/// 
/// Attributes:
///     value1 (str): 値1.
///     value2 (int): 値2.
#[gen_stub_pyclass]
#[pyclass]
pub struct MyClass {
    // 値1.
    #[pyo3(get, set)]
    value1: String,
    // 値2.
    #[pyo3(get, set)]
    value2: i32,
}

Pythonのプロパティー（フィールドに#[pyo3(get, set)]を付けたり、メソッドに#[getter], #[setter]を付けたりしたもの）は、pdoc3で生成されたAPIドキュメントには型情報が現れない。

なので、Attributesセクションを作って、プロパティーを列挙する。
Attributesのプロパティーの形式は、「プロパティー名 (型): 説明」。

関数・メソッド

関数やメソッドのセクションには以下のようなものを書く。

#[gen_stub_pymethods]
#[pymethods]
impl MyClass {
    /// コンストラクター.
    ///
    /// Args:
    ///     value1 (str): 値1.
    ///     value2 (int): 値2.
    ///
    /// Returns:
    ///     MyClass: サンプルクラスのオブジェクト.
    #[new]
    fn new(value1: String, value2: i32) -> Self {
        Self {
            value1,
            value2,
        }
    }

#[new]によるコンストラクターのDocstringは、pdoc3によるAPIドキュメントには現れないが、pyo3-stub-genで生成される型スタブファイルには転記される。

    /// 値1.
    #[getter]
    fn my_value(&self) -> &str {
        &self.value1
    }

#[getter]や#[setter]によるプロパティーのアクセッサ―メソッドのDocstringは、pdoc3によるAPIドキュメントではvariablesセクションに現れる。
ここで引数や戻り値を書くとクラスのAttributesセクションに書いたものと被って冗長になるので、プロパティーのアクセッサ―メソッドのDocstringにはタイトルだけ書くのが良いと思う。

    〜
}

列挙型

列挙型のPython Docstringの例。

/// サンプル列挙型.
/// 
/// Attributes:
///     RED: 赤.
///     GREEN: 緑.
///     BLUE: 青.
#[gen_stub_pyclass_enum]
#[pyclass]
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[allow(clippy::upper_case_acronyms)]
pub enum Color {
    /// 赤.
    RED,
    /// 緑.
    GREEN,
    /// 青.
    BLUE,
}

列挙型もクラスと同様にAttributesで列挙子を書くが、型は書かない。（列挙子は全て同じ列挙型だしｗ）

列挙子に付けたドキュメンテーションコメントは、pdoc3によるAPIドキュメントには現れないが、pyo3-stub-genで生成される型スタブファイルには転記される。