📝

Rust初学者必見！`cargo doc --open`で効率的に学習しよう

に公開
Rust
tech

最近Rustにハマっている初学者です。
間違えや改善点などあればコメントいただけると嬉しいです🙇

本題ですが皆さんはプロジェクトで使用している外部ライブラリ（crate）のドキュメントを調べる時、どうしていますか？
ブラウザでcrates.ioを開いて検索したり、公式サイトを探し回ったりしている人はいますか？

実は、もっと簡単で効率的な方法があります。
それが今回紹介するcargo doc --openコマンドです。

cargo doc --openとは？

cargo doc --openは、現在のプロジェクトで使用しているすべての依存関係（dependencies）のドキュメントを自動生成し、ブラウザで開いてくれる便利なCargoコマンドです。

基本的な使い方

cargo doc --open

たったこれだけです。

コマンドを実行すると…

  1. プロジェクトの依存関係を解析
  2. すべてのcrateのドキュメントをローカルに生成
  3. 自動的にブラウザでドキュメントページを開く

何が便利なのか？

1. オフラインでも使える

一度生成したドキュメントはtarget/docフォルダに保存されるため、インターネット接続がなくてもドキュメントを参照できます。

2. プロジェクト固有の情報

使用している正確なバージョンのドキュメントが表示されます。
オンラインで最新版を見て「あれ、このメソッドが見つからない」といった混乱がなくなると思います。

3. 依存関係が一覧で見える

プロジェクトで使用している全てのcrateが一つのページに整理されて表示されます。
関連するライブラリを横断的に調べるときに非常に便利です。

4. 高速アクセス

ローカルに生成されるため、ページの読み込みが非常に高速です。

実際に使ってみた

準備：サンプルプロジェクトを作成

cargo new doc_sample
cd doc_sample

Cargo.tomlに依存関係を追加

[dependencies]
serde = "1.0"
tokio = { version = "1.0", features = ["full"] }
reqwest = { version = "0.11", features = ["json"] }

ドキュメントを生成して開く

cargo doc --open

実行後、ブラウザで以下のようなページが開きます

  • serdeのドキュメント
  • tokioのドキュメント
  • reqwestのドキュメント
  • その他の間接的な依存関係すべて

より便利な使い方

自分のコードのドキュメントも含める

cargo doc --open --document-private-items

プライベートな関数やモジュールのドキュメントも生成されます。

依存関係なしで自分のプロジェクトのみ

cargo doc --open --no-deps

外部crateは除いて、自分のプロジェクトのドキュメントのみを生成します。

特定のパッケージのみ

cargo doc --open -p serde

指定したパッケージのドキュメントのみを生成します。

学習効率を上げるコツ

1. コードを書く前にドキュメントを確認

新しいcrateを使う前に、まずcargo doc --openでドキュメントを生成し、APIの全体像を把握しましょう。

2. エラーが出たらすぐドキュメント確認

コンパイルエラーが出た際も、該当するcrateのドキュメントをすぐに確認できます。
正しい使い方やサンプルコードが豊富に載っています。

3. 関連するcrateの発見

ドキュメントページでは、関連するcrateも一覧で見られるため、新しい便利なライブラリを発見するきっかけにもなります。

注意点

初回生成時間

プロジェクトの依存関係が多い場合、初回のドキュメント生成には時間がかかることがあります。

ディスク使用量

生成されたドキュメントはtarget/docに保存され、それなりのディスク容量を使用します。

不要になったらcargo cleanで削除できます。

まとめ

cargo doc --openは、Rust学習の効率を大幅に向上させてくれる非常に有用なコマンドです。
特に初学者の方には以下の点でおすすめかと。

  • 学習コストの削減：ブラウザでの検索時間を短縮
  • 正確な情報：使用中のバージョンに対応した正確なドキュメント
  • オフライン対応：インターネット環境に左右されない&ググる手間削減

まだ使ったことがない方は、ぜひ一度試してみてください。
Rustの開発体験の良さを実感できるはずです。

この記事がRust学習の一助となれば幸いです。
他にも便利なCargoコマンドがあれば、ぜひコメントで！

Discussion