• 2024/3/28
• 2分

【Swift】ドキュメントコメントの記述方法！ショートカット

＼ アプリをリリースしました ／

友達や家族の誕生日をメモ！通知も届く-みんなの誕生日-

posted withアプリーチ

環境

• Xcode：15.0.1
• iOS：17.0
• Swift：5.9
• macOS：Sonoma 14.1

Swiftのドキュメントコメントとは？

Swiftのドキュメントコメントとはコード内の要素(関数、クラス、メソッド、プロパティなど)の説明やドキュメントを記述するための特別なコメント形式です。普通のコメントとは異なり、自動でハイライトが効いたりドキュメントブラウザなどのツールで自動的に解析されてみやすく表示されるようになります。

記述方法は通常のコメントアウト(//)ではなく///で行います。

/// 関数の説明
///
/// - Parameters:
///   - a: 1つ目の引数の説明
///   - b: 2つ目の引数の説明
/// - Returns: 返り値の説明
///
/// Example:
/// ```
/// let num = sampleFunction(a: 5, b: 10)
/// print(" \(num)")
/// ```
func sampleFunction(a: Int, b: Int) -> Int {
    return a + b
}

ドキュメントコメントを記述することでその関数の詳細を「Quick Help」から参照することができるようになります。

ショートカット

ドキュメントコメントを1文字ずつ記述するのは骨が折れるのでショートカットを使うと便利です。ショートカットは「option + command + /」です。ドキュメントコメントを追加したい関数を選択した状態でショートカットコマンドを実行すると自動でパラメータや返り値など必要なコメントを追加してくれます。

ドキュメントコメントの種類

引数や返り値以外にも種類はたくさんあるようです。

/// 関数の説明
///
/// - Warning: 警告
/// - Throws: エラーをスロー
/// - Version: 1.0.0
func sampleFunction(a: Int, b: Int) -> Int {
    return a + b
}

他にもたくさん種類があるようです。詳細は以下の記事にまとめてくれている方がいました。

Qiita：Swiftのドキュメントコメント

まだまだ勉強中ですので間違っている点や至らぬ点がありましたら教えていただけると助かります。

ご覧いただきありがとうございました。