ドキュメント

Dartのドキュメントコメントの書き方

ドキュメントコメントを記述するためにその書き方を調べた。 Effective Dart: Documentation dart docがドキュメントコメントをパースしてdoc pageを生成してくれる。 パッケージをpub.devで公開する場合、ドキュメントコメントがあると利用者が迷わず利用することができる。またpub.devがPub Pointsをつけるが、評価内容にドキュメントコメントが書かれているかが含まれている。 文法ドキュメントコメントは///か/** */で記述する。///が好まれる。 /// Document comment title /// /// ... libraryディレクティブにライブラリの包括的なコメントを書くlibraryディレクティブにライブラリのドキュメントコメントを付けると良い。libraryディレクティブが無い場合はドキュメントコメントを書くためだけにlibraryディレクティブを記述するのも良い。libraryディレクティブのドキュメントコメントとして以下を記述するとよい。 このライブラリは何のためにあるのか、一文で要約する。ライブラリ全体で使用される用語の説明。API の使い方を説明した完全なコードサンプル。最も重要な、あるいは最も一般的に使用されるクラスや関数へのリンク。ライブラリが関係しているドメインに関する外部参照へのリンク。プライベートAPIのコメントプライベートAPIのドキュメントコメントは利用者ではなく開発者に役立つ。