docコメント内の簡易な初期化

説明

docコメントを書く際に、構造体を初期化するのに多大な労力がかかる場合は、構造体を引数に取るヘルパー関数でコード例をラップした方が手っ取り早いかもしれません。

動機形成

多数の、または複雑なパラメータや複数のメソッドが、構造体に存在するとしましょう。これらのメソッドにはそれぞれコード例があるはずです。

例:

struct Connection {
    name: String,
    stream: TcpStream,
}

impl Connection {
    /// 接続を介してリクエストを送信
    ///
    /// # Example
    /// ```no_run
    /// # // コード例を機能させるにはボイラーテンプレートが必要になります。
    /// # let stream = TcpStream::connect("127.0.0.1:34254");
    /// # let connection = Connection { name: "foo".to_owned(), stream };
    /// # let request = Request::new("RequestId", RequestType::Get, "payload");
    /// let response = connection.send_request(request);
    /// assert!(response.is_ok());
    /// ```
    fn send_request(&self, request: Request) -> Result<Status, SendErr> {
        // ...
    }

    /// なんと、ここでも同じボイラーテンプレートが必要です！
    fn check_status(&self) -> Status {
        // ...
    }
}

例

このような Connection や Request を生成するボイラーテンプレートすべてをタイピングする代わりに、それらを引数として受け取るヘルパー関数をラッパーとして作成する方が簡単です：

struct Connection {
    name: String,
    stream: TcpStream,
}

impl Connection {
    /// 接続を介してリクエストを送信
    ///
    /// # Example
    /// ```
    /// # fn call_send(connection: Connection, request: Request) {
    /// let response = connection.send_request(request);
    /// assert!(response.is_ok());
    /// # }
    /// ```
    fn send_request(&self, request: Request) {
        // ...
    }
}

注意 上記の例における、 assert!(response.is_ok()); という行は、呼び出されない関数内にあるため、実際にはテスト中に実行されません。

長所

この方がはるかに簡潔で、コード例中のコードの繰り返しを避けることができます。

短所

コード例が関数定義の中にあるので、コードはテストされません。しかし cargo test を実行することで、コンパイルできたかどうかはチェックされます。ですから、このパターンは no_run が必要なときに便利です。このパターンを使う場合、 (実行されないため) no_run を追加する必要はありません。

議論

アサーションが必要ない場合は、このパターンがうまく機能します。

もしアサーションが必要であるなら、別の方法として、ヘルパーインスタンスを作成するpublicメソッドを #[doc(hidden)] でアノテーションして作成する方法があります。これにより、このメソッドはcrateのパブリックAPIの一部として、 rustdoc の内部で呼び出すことが可能になります。