ドキュメントコメントを記述するためにその書き方を調べた。
dart docがドキュメントコメントをパースしてdoc pageを生成してくれる。
パッケージをpub.devで公開する場合、ドキュメントコメントがあると利用者が迷わず利用することができる。またpub.devがPub Pointsをつけるが、評価内容にドキュメントコメントが書かれているかが含まれている。
文法
ドキュメントコメントは///か/** */で記述する。///が好まれる。
/// Document comment title
///
/// ...
libraryディレクティブにライブラリの包括的なコメントを書く
libraryディレクティブにライブラリのドキュメントコメントを付けると良い。libraryディレクティブが無い場合はドキュメントコメントを書くためだけにlibraryディレクティブを記述するのも良い。libraryディレクティブのドキュメントコメントとして以下を記述するとよい。
- このライブラリは何のためにあるのか、一文で要約する。
- ライブラリ全体で使用される用語の説明。
- API の使い方を説明した完全なコードサンプル。
- 最も重要な、あるいは最も一般的に使用されるクラスや関数へのリンク。
- ライブラリが関係しているドメインに関する外部参照へのリンク。
プライベートAPIのコメント
プライベートAPIのドキュメントコメントは利用者ではなく開発者に役立つ。
要約
ドキュメントコメントの1行目は読者がコメントを読みすすめるか決定することの役に立つように、簡潔な説明を記述する。dart docは最初の段落を要約とみなす。2行目は段落を分けるために空行を入れる。
/// Append string
///
/// ..
読者が知らないことを記述する
クラスの名前や適合インターフェースなどは実装からすぐに分かるので、ドキュメントコメントでは読者が知らないことを説明すると良い。特に記述することがないのであればドキュメントコメントは省略する。
関数やメソッドのコメントは三人称の動詞で始める
/// Returns generated string...
String generateString()...
変数・ゲッター・セッターのコメントは名詞句で始める
そのプロパティが何であるかを強調する。 dart docはゲッターとセッターの両方にコメントがある場合、セッターのコメントを破棄する。
ライブラリや型のコメントは名詞句で始める
クラスのドキュメントコメントでは型のインバリアントを説明し、使用する用語を定め、クラスのメンバに対する他のドキュメントコメントへのコンテキストを提供する。
コードサンプルを記載することを検討する
インスコープ識別子を参照するために角括弧を使用する
変数名・メソッド名・型名などを書く括弧で囲むとdart docはその名前を検索して、関連するAPIドキュメントにリンクする。
特定のクラスのメンバーにリンクする場合はクラスメイトメンバー名をドットで区切る。
ドット構文は名前付きコンストラクタも参照できる。無名コンストラクタはクラス名に.newを付ける。
/// Throws a [StateError]
/// Similar to [Duration.isDays]
/// [Point.new] or [Point.polar]
パラメータ・返値・例外を文章で説明する
他の言語では@paramなどのタグやセクションを使用するが、Dartでは文章で記述する。
/// Defines a flag.
///
/// Throws an [ArgumentError] if there is already an option named [name] or
/// there is already an option using abbreviation [abbr]. Returns the new flag.
Flag addFlag(String name, String abbr) => ...
メタデータの注釈の前にドキュメントコメントを記述する
/// A button that can be flipped on and off.
@Component(selector: 'toggle')
class ToggleComponent {}
Markdown
Markdownでフォーマッティングできる。 ただしMarkdownを過度に使用せずフォーマットを少なくする。 HTMLのテーブルなどを利用することもあるが、できる限りHTMLは利用しない。 コードブロックはbacktickフェンスを利用する。
/// ```dart
/// var ...
/// ```
その他
明確・正確・簡潔に記述する。 明らかな場合を除き略語や頭字語を避ける。 メンバーのインスタンスを表すにはtheではなくthisを利用する。
class Box {
/// The value this wraps.
Object? _value;
/// True if this box contains a value.
bool get hasValue => _value != null;
}
