Dartでドキュメントコメントを使用する方法
ルール (かいつまんで)
///
または/** */
を用いて記述する。///
が好まれる- 1行目に概要、2行目は空けて3行目から詳細を記述する
- 詳細は箇条書きや定形でなく、散文で記述する
- 引数等のスコープ内のプロパティの記述は角括弧を使用する。そうすることで、Dart docが自動で判別して関連ドキュメントにリンクしてくれたりする
- Markdownが使用できる。が、過度な使用は避ける
- HTMLも使用できる (tableタグとか)。が、可能な限り使用は避ける
- サンプルコードをMarkdownのコメント機能で記述できる。この方法は推奨される
- 以上の規則を守って記述することで、Dart docがユーザー側にいい感じに表示してくれる
サンプル
/// 10進数を16進数に変換する
///
/// 10進数の数値を16進数の文字列に変換する。
/// [dec] には浮動小数点数も使用できる。
///
/// ```dart
/// decToHex(16) == '10'
/// ```
当然だが、パブリッシュにするライブラリの場合は英語で記述する。
ローカルライブラリやAPIとかは日本語でも全然OK。