2.8. プロジェクトドキュメントの構築
rustdoc ではなく cargo doc
の使用を考慮してください。このコマンド cargo doc
は、rustdoc ユーティリティーを使用します。
cargo doc
パブリック関数、変数、メンバーに対してのみ、ドキュメントコメントを抽出します。
Rust コードには、ドキュメントへの抽出用のコメントを含めることができます。コメントは Markdown 言語に対応しています。
cargo ツールを使用してプロジェクトのドキュメンテーションを構築するには、プロジェクトディレクトリーに移動し、cargo
ツールを実行します。
Red Hat Enterprise Linux 7 の場合:
scl enable rust-toolset-1.35 'cargo doc --no-deps'
$ scl enable rust-toolset-1.35 'cargo doc --no-deps'
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Red Hat Enterprise Linux 8 の場合:
cargo doc --no-deps
$ cargo doc --no-deps
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
これにより、プロジェクトのソースコードにある特別なコメントから保存したドキュメントが抽出され、HTML 形式でドキュメントが書き込まれます。
-
サードパーティーライブラリーなど、生成されたドキュメントの依存関係を含める
--no-deps
オプションを省略します。 -
ブラウザーで生成されたドキュメントを開く
--open
オプションを追加します。
例2.7 プロジェクトドキュメントの構築
この例では、例2.6「プロジェクトへの依存関係の追加および cargo で構築」 に従って依存関係で Rust プロジェクト helloworld
を正常にビルドしていることを前提としています。
ディレクトリー helloworld
に移動し、以下のソースコードが含まれるファイル src/main.rs
を編集します。
このコードには、パブリック関数 print_output()
が含まれるようになりました。helloworld
プログラム、print_output()
関数、および main()
関数にはドキュメントコメントがあります。
cargo doc
コマンドを実行し、プロジェクトのドキュメンテーションを構築します。
Red Hat Enterprise Linux 7 の場合:
scl enable rust-toolset-1.35 'cargo doc --no-deps'
$ scl enable rust-toolset-1.35 'cargo doc --no-deps' Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.31 secs
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Red Hat Enterprise Linux 8 の場合:
cargo doc --no-deps
$ cargo doc --no-deps Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 0.31 secs
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
インストールされていない場合は、ツリー ツール (デフォルトの Red Hat Enterprise Linux リポジトリーで利用できます) をインストールします。
yum install tree
# yum install tree
結果を確認します。
cargo はプロジェクトのドキュメンテーションを構築します。このドキュメントを表示するには、ブラウザー target/doc/helloworld/index.html
でファイルを開きます。生成されたドキュメントには、公開されていないため、main()
関数に関する記述は含まれません。
--no-deps
オプションを指定せずに cargo doc
コマンドを実行して、依存関係ライブラリーの time および libc を含むプロジェクトのドキュメントを構築します。
Red Hat Enterprise Linux 7 の場合:
scl enable rust-toolset-1.35 'cargo doc'
$ scl enable rust-toolset-1.35 'cargo doc' Documenting libc v0.2.32 Documenting time v0.1.38 Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 3.41 secs
Copy to Clipboard Copied! Toggle word wrap Toggle overflow Red Hat Enterprise Linux 8 の場合:
cargo doc
$ cargo doc Documenting libc v0.2.32 Documenting time v0.1.38 Documenting helloworld v0.1.0 (file:///home/vslavik/helloworld) Finished dev [unoptimized + debuginfo] target(s) in 3.41 secs
Copy to Clipboard Copied! Toggle word wrap Toggle overflow
以下の tree
コマンドを使用して、フォルダー構造を確認します。
tree ls -d target/doc/*/
$ tree
...
92 directories, 11804 files
$ ls -d target/doc/*/
target/doc/helloworld/ target/doc/implementors/ target/doc/libc/ target/doc/src/ target/doc/time/
作成されるドキュメントは、依存関係ライブラリーの time および libc にも対応し、それぞれ target/doc/
ディレクトリーに別のサブディレクトリーとして存在します。
関連資料
cargo doc
ツールおよびその機能の詳しい説明は、本書の対象外となっています。詳細は、以下に記載のドキュメントを参照してください。
- 公式 Rust プログラミング言語のドキュメントの 便利なドキュメントコメント