ルール (かいつまんで)

• ///または/** */ を用いて記述する。///が好まれる
• 1行目に概要、2行目は空けて3行目から詳細を記述する
• 詳細は箇条書きや定形でなく、散文で記述する
• 引数等のスコープ内のプロパティの記述は角括弧を使用する。そうすることで、Dart docが自動で判別して関連ドキュメントにリンクしてくれたりする
• Markdownが使用できる。が、過度な使用は避ける
• HTMLも使用できる (tableタグとか)。が、可能な限り使用は避ける
• サンプルコードをMarkdownのコメント機能で記述できる。この方法は推奨される
• 以上の規則を守って記述することで、Dart docがユーザー側にいい感じに表示してくれる

サンプル

/// 10進数を16進数に変換する
/// 
/// 10進数の数値を16進数の文字列に変換する。
/// [dec] には浮動小数点数も使用できる。
/// 
/// ```dart
/// decToHex(16) == '10'
/// ```

当然だが、パブリッシュにするライブラリの場合は英語で記述する。
ローカルライブラリやAPIとかは日本語でも全然OK。