dartdoc コメントによるドキュメント作成
pub.dev で表示されるドキュメントを書きます
「dartdoc コメントによるドキュメント作成」はCoddyKit上の無料Dart Academyレッスンです。 これはレッスン2/4です。 下記で完全なレッスンを無料で読むことができます。その後、ブラウザ内の組み込みコードエディタと24時間対応のAIチューターでハンズオン演習できます。 これはDart Academy学習パスの一部であり、ウェブとCoddyKitアプリ全体で進捗が同期されます。 Dart Academyコースには全4レッスンが含まれています。
ドキュメントもプロダクトの一部
優れたパッケージには優れたドキュメントがあります。Dart では特別なコメントから閲覧可能なリファレンスを生成できるため、documentation は後付けではなく、重要な機能の一つです。📝
トリプルスラッシュのドキュメントコメント
ドキュメントコメントは3つのスラッシュで始まります。この doc comments は宣言のすぐ上に置き、ユーザー向けにその役割を説明します。
/// Adds two numbers and returns the sum.
int add(int a, int b) => a + b;最初に1行の要約を書く
すべてのドキュメントコメントは、短い summary 文1つで始めます。ツールは一覧でこの1行目を最初に表示するため、それだけで内容が明確に伝わるようにします。
Markdown に対応している
ドキュメントコメントでは Markdown を使えるため、強調、リスト、リンクを追加できます。ほとんど手間をかけずに、pub.dev の表示ページを整ったものにできます。
/// Returns the **first** matching item.ほかのシンボルへリンクする
名前を角括弧で囲むと、機能する cross-link を作成できます。生成されたドキュメントから、関連するクラスやメソッドへ直接移動できます。
/// See [add] for the inverse of [subtract].フェンス付きブロックにコード例を書く
コメント内のフェンス付きコードブロックに実際の使用例を示します。短い example は長い説明文よりも早く理解を促し、動作することもユーザーに伝えられます。
すべての公開メンバーをドキュメント化する
各 public クラス、関数、フィールドをドキュメント化するようにします。アンダースコアで始まる非公開メンバーは省略できますが、エクスポートするものには説明を添えてください。
ライブラリレベルのドキュメント
ライブラリディレクティブの上にドキュメントコメントを置くと、ファイル全体を説明できます。この library comment は、API のその部分を説明する導入文になります。
/// Math helpers for everyday use.
library calc;dartdoc でサイトを生成する
dartdoc ツールを実行すると、コメントを静的なウェブサイトに変換できます。pub.dev では、公開時に自動で実行されます。
dart doc .ドキュメントの充実度でポイントを得る
pub.dev は、ドキュメントが充実したパッケージを評価します。高い doc coverage はスコアを引き上げ、依存関係を選ぶ人に品質の高さを示します。⭐
ドキュメントをコードの近くに保つ
ドキュメントコメントはコードの横にあるため、コードと一緒に更新しやすくなります。古い docs はバグと同じように扱い、動作を変更したときは修正してください。
確認問題
Dart がドキュメントコメントとして扱うコメント形式はどれですか？
まとめ：表示されるドキュメント
これで、トリプルスラッシュの doc comments を書き、シンボルへのリンクや例を追加し、dart doc でサイトを生成できるようになりました。明確なドキュメントがユーザーを引きつけます。🙌
AI チューターと学ぶ Dart — 無料
ブラウザでリアルコードを書いて実行し、24/7 の AI チューターから瞬時にサポートを受け、ウェブまたはアプリで続きから学習できます。
- コース
- 30
- レッスン
- 120
よくある質問
「dartdoc コメントによるドキュメント作成」レッスンは無料ですか？
はい。「dartdoc コメントによるドキュメント作成」の完全なテキストはこのウェブで無料で読めます。インタラクティブに演習し（組み込みコードエディタと24時間対応のAIチューター）、Dart Academyコースの残りをアンロックするには、CoddyKit PROにアップグレードしてください。 Dart Academyコースには全4レッスンが含まれています。
「dartdoc コメントによるドキュメント作成」で何を学びますか？
pub.dev で表示されるドキュメントを書きます ブラウザで直接実行するハンズオンコードでDart Academyを演習し、24時間対応のAIチューターがレッスンを進める中での質問に答えます。
Dart Academyを始めるのに経験は必要ですか？
事前経験は必要ありません。CoddyKitのDart Academyは初級者から上級者向けに構成されているため、ここから始めるか最初から始めて、自分のペースで進むことができます。 これはレッスン2/4です。
「dartdoc コメントによるドキュメント作成」レッスンにはどのくらい時間がかかりますか？
ほとんどのCoddyKitレッスンは約5～10分かかります。各レッスンはコンパクトでインタラクティブなので、着実に進歩し、ウェブとアプリ全体で正確に前回の場所から再開できます。
このDart Academyレッスンでコードを書いて実行できますか？
はい。すべてのDart Academyレッスンに組み込みコードエディタが含まれているため、ブラウザでリアルコードを書いて実行し、即座のAIフィードバックを取得できます。ローカル設定は不要です。
このコースのすべてのレッスン
- 公開可能なライブラリの構成
- dartdoc コメントによるドキュメント作成
- Lint、フォーマット、pana スコア
- dart pub publish で pub.dev に公開