Zenn
🐙

/// ドキュメンテーションコメント使ってますか？

2025/03/09に公開
Flutter
メモ
tech

普段何気なく使うコメントアウト以外に
・ドキュメンテーションコメント
というのがあります。
最近まで違いを理解しておらず、ただの好みなんだろうな〜と思っていたのですが、ググったらちゃんと違いあったので忘れない様に簡単にメモとしてまとめます。

通常のコメント

いつも見てるであろうこれ
// が2つ。

void main() {
  // こういうやつ
  print('Hello');
}

ドキュメンテーションコメント

/// が3つがドキュメンテーションコメント

/// カスタムボタンウィジェット
/// 
/// アプリケーション全体で統一されたスタイルのボタンを提供。
/// [text] ボタンに表示するテキスト
/// [onPressed] ボタンがタップされたときのコールバック
/// [color] ボタンの背景色（オプション）
class CustomButton extends StatelessWidget {
  final String text;
  final VoidCallback onPressed;
  final Color? color;

  const CustomButton({
    Key? key, 
    required this.text, 
    required this.onPressed, 
    this.color,
  }) : super(key: key);

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: onPressed,
      style: ElevatedButton.styleFrom(
        backgroundColor: color,
      ),
      child: Text(text),
    );
  }
}

ドキュメンテーションコメントの書き方

  • ClassやWidgetの説明：そのクラスやウィジェットが何をするためのものかを簡潔に
  • パラメータの説明：[paramName] の形式でパラメータを説明
  • 戻り値の説明：メソッドが何を返すのかを明記
  • 例の提示：複雑な機能の場合は使用例を含める
  • マークダウン記法：箇条書きや強調などのマークダウンが使える
/// ユーザー情報を取得するメソッド
/// 
/// [userId] 取得するユーザーのID
/// 
/// 返り値は [User] オブジェクト。ユーザーが見つからない場合は null
/// 
/// 例:
/// ```dart
/// final user = await getUserById(123);
/// if (user != null) {
///   print(user.name);
/// }
/// ```
Future<User?> getUserById(int userId) async {
  // 実装...
}

ドキュメンテーションコメントを使うメリット

  1. 自己文書化コード：コードとドキュメントが常に一緒にあるため、最新の状態を維持しやすい
  2. IDE統合：こんな感じでホバー時に情報表示される
  3. API設計の明確化：引数や戻り値の意図が明確になる
  4. 自動ドキュメント生成：Dartdocという機能を使ってドキュメントを簡単に生成できる

Dartdocの利用方法

下記のコマンドを実行することで、ドキュメントをHTML形式で生成できる。

# dartdoc パッケージをグローバルにインストール
flutter pub global activate dartdoc

# インストール後に実行
flutter pub global run dartdoc

doc/apiにドキュメントが生成される

ブラウザで確認するには下記のコマンドを叩く

open doc/api/index.html

そうするとこのように表示される。

まとめ

ドキュメンテーションコメント（/// で始まるコメント）は、単なるコードの説明ではなく、ドキュメント生成などの機能を持つコメントアウトだという事が分かりました。

特に以下のような場面で積極的に活用すると効果的だと思いました。

  • 複雑なクラスやメソッドの説明
  • パラメータや戻り値の意図を明確にしたい場合
  • 将来のメンテナンス性を高めたい場合

今まで何気なく書いていたコメントも、ドキュメンテーションコメントを使うだけで、便利なドキュメントに変わります。
普段の開発でも活用してみてください！

Discussion