Swiftで学ぶ！ドキュメントコメントのたった10の方法

はじめに
●Swiftとドキュメントコメントの基本
- ○Swiftの特徴
- ○ドキュメントコメントとは？
●ドキュメントコメントの作成方法
●ドキュメントコメントの応用
●ドキュメントコメントの注意点と対処法
- ○サンプルコード7：避けるべき書き方とその理由
- ○サンプルコード8：頻出するエラーとその対処法
●ドキュメントコメントのカスタマイズ方法
- ○サンプルコード9：カスタムテーマの適用方法
- ○サンプルコード10：独自のタグを作成する方法
まとめ

はじめに

Swiftを学んでいる皆さん、コードの品質を向上させるためには、そのコードを読む人が何をしているのかを簡単に理解できることが非常に重要です。

ドキュメントコメントは、その手助けをしてくれる素晴らしいツールです。

この記事を通じて、Swiftでのドキュメントコメントの基本的な使い方から、応用、カスタマイズ方法までを10の実践的なサンプルコードで学ぶことができます。

●Swiftとドキュメントコメントの基本

Swiftは、Appleのプラットフォーム用に開発された新しいプログラミング言語で、そのシンタックスや設計思想が多くの開発者から注目を浴びています。

一方、ドキュメントコメントは、コードの中に直接書かれるコメントで、特にSwiftでは非常に強力な機能を持っています。

○Swiftの特徴

Swiftは、安全性やパフォーマンスに優れ、モダンな構文を持つことが特徴です。

具体的には、コンパイル時に多くのエラーをキャッチすることができるため、ランタイムエラーを大幅に削減することができます。

また、直感的なシンタックスにより、初心者でも簡単に学ぶことができる点も大きな魅力となっています。

○ドキュメントコメントとは？

ドキュメントコメントは、Swiftのコード内で特定のフォーマットを使って記述されるコメントのことを指します。

このコメントは、Xcodeや他のドキュメント生成ツールによって読み取られ、APIのリファレンスなどの公式ドキュメントとして出力されます。

このため、ドキュメントコメントを適切に書くことで、他の開発者があなたのコードを理解しやすくなるだけでなく、公式なドキュメントとしての品質も向上します。

このコードでは、基本的なドキュメントコメントの書き方を表しています。

この例では、関数addNumbersについての説明を、ドキュメントコメントを使用して記述しています。

/// 加算関数
/// - Parameters:
///   - a: 第一の整数
///   - b: 第二の整数
/// - Returns: 2つの整数の合計
func addNumbers(a: Int, b: Int) -> Int {
    return a + b
}

こちらのコードは、2つの整数を引数として受け取り、その合計値を返すシンプルな関数を示しています。

そして、その関数の上にはドキュメントコメントが記述されており、関数の説明や引数、戻り値についての情報が記載されています。

Xcodeや他のIDEでこの関数の名前の上にマウスカーソルを置くと、上記のドキュメントコメントが表示され、関数の動作や引数、戻り値の情報を手軽に確認することができます。

●ドキュメントコメントの作成方法

Swiftのドキュメントコメントの作成は非常に簡単です。

しかし、その中には様々な書き方やタグが存在しています。

ここでは、ドキュメントコメントを作成する上での基本的な方法や、それを更に活用する方法を3つのサンプルコードを通して紹介します。

○サンプルコード1：基本的なドキュメントコメントの書き方

このコードでは、Swiftでの基本的なドキュメントコメントの書き方を表しています。

この例では、関数の上にドキュメントコメントを記述して関数の説明を追加しています。

/// 2つの数を足す関数
/// - Parameters:
///   - a: 第1の数字
///   - b: 第2の数字
/// - Returns: 2つの数字の合計
func sum(a: Int, b: Int) -> Int {
    return a + b
}

上記のコメントは、sum関数の上に記述されており、この関数が何をするのか、どんな引数を取り、どんな値を返すのかを簡潔に説明しています。

このコメントを記述することで、他の開発者がこの関数を使用する際に、関数の機能や使用方法を瞬時に理解する手助けとなります。

○サンプルコード2：関数やメソッドの説明を記述する

関数やメソッドのドキュメントコメントでは、より詳細な情報を提供することが期待されます。

このコードでは、関数の引数や戻り値、使用例などを含むより詳細なドキュメントコメントの書き方を表しています。

/**
  文字列を2回繰り返す関数
  - Parameters:
    - string: 繰り返される文字列
  - Returns: 繰り返した文字列
  - Example:
    - `doubleString("Hello")` は "HelloHello" を返します。
*/
func doubleString(string: String) -> String {
    return string + string
}

この関数doubleStringは、与えられた文字列を2回繰り返して返すものです。

その機能や使い方がドキュメントコメントで詳しく説明されています。

○サンプルコード3：変数やプロパティの説明を記述する

変数やプロパティも、その用途や内容を他の開発者に知らせるためにドキュメントコメントを活用することができます。

このコードでは、プロパティのドキュメントコメントの基本的な書き方を表しています。

/// 人の名前を表すプロパティ
var name: String = ""

こちらのコードは非常にシンプルですが、nameというプロパティが何を意味しているのかを明確にするためのコメントが付けられています。

●ドキュメントコメントの応用

Swiftのドキュメントコメントは基本的な書き方だけでなく、多様なタグを利用することでさらに詳細な情報を記述することが可能です。

ここでは、ドキュメントコメントの応用的な書き方や、さらに高度な機能を活用するためのサンプルコードを3つ紹介します。

○サンプルコード4：特定のタグを利用した詳細な説明

このコードでは、特定のタグを使用してドキュメントコメントを更に詳細に記述する方法を表しています。

この例では、throwsタグやseealsoタグを活用して、関数のエラーを投げる条件や関連する情報を追記しています。

/**
  文字列を整数に変換する関数
  - Parameters:
    - string: 変換する文字列
  - Throws: 変換できない場合のエラー
  - Returns: 変換された整数
  - SeeAlso: `Int.init?(_:)`
*/
func convertToInt(string: String) throws -> Int {
    guard let value = Int(string) else {
        throw ConversionError.invalidFormat
    }
    return value
}

この関数は、与えられた文字列を整数に変換するものです。

変換に失敗した場合、エラーを投げます。

○サンプルコード5：コードのリンクを挿入する方法

このコードでは、ドキュメントコメント内で他のコードや関数へのリンクを挿入する方法を表しています。

この例では、関連する型やメソッドへのリンクを追加しています。

/**
  ユーザーの年齢を元に成年か未成年かを判断する関数
  - Parameters:
    - age: ユーザーの年齢
  - Returns: 成年か未成年かの文字列
  - SeeAlso: `[User]`, `isAdult(user:)`
*/
func judgeAgeCategory(age: Int) -> String {
    return age >= 20 ? "成年" : "未成年"
}

この関数は、与えられた年齢を元に成年か未成年かを判断し、その結果を文字列で返します。

○サンプルコード6：画像やリンクの挿入

Swiftのドキュメントコメントでは、外部のリンクや画像へのリンクも挿入することができます。

この方法を活用すると、コメントが更にわかりやすくなります。

/**
  画像のURLから画像をダウンロードする関数
  - Parameters:
    - url: 画像のURL
  - Returns: ダウンロードされた画像
  - SeeAlso: 
    - [公式ドキュメンテーション](https://developer.apple.com/documentation/)
    - ![イメージサンプル](https://example.com/sample.jpg)
*/
func downloadImage(from url: String) -> UIImage? {
    // 画像のダウンロード処理
}

この関数は、指定されたURLから画像をダウンロードするものです。

ドキュメントコメント内には関連する公式ドキュメンテーションへのリンクやサンプルの画像へのリンクが挿入されています。

●ドキュメントコメントの注意点と対処法

Swiftのドキュメントコメントは非常に便利で、コードの解説を自動で生成するのに役立ちます。

しかし、正しくない使い方や誤解を招く書き方をすると、読む人を混乱させることがあります。

ここでは、ドキュメントコメントの書き方での注意点と、それをどのように対処するかについて詳しく解説します。

○サンプルコード7：避けるべき書き方とその理由

このコードでは、避けるべきドキュメントコメントの書き方とその理由を表しています。

特に、情報が重複することで読む人が混乱する可能性があるため、適切な情報のみを記述することが求められます。

/**
  文字列を変換する関数
  - Parameters:
    - string: 変換する文字列。文字列を変換します。
  - Returns: 変換された文字列。変換した文字列を返します。
*/
func convertString(string: String) -> String {
    // 文字列の変換処理
    return string
}

この関数のドキュメントコメントでは、ParametersやReturnsの説明が重複しており、読む人にとって冗長です。

簡潔かつ必要な情報のみを記述することで、よりわかりやすいドキュメントを作成することができます。

○サンプルコード8：頻出するエラーとその対処法

ドキュメントコメントを書いていると、特定のエラーに遭遇することがあります。

このコードでは、頻出するエラーとその対処法を紹介しています。

/**
  文字列を変換する関数
  - Parameters
    - string: 変換する文字列
  - Returns: 変換された文字列
*/
func anotherConvertString(string: String) -> String {
    // 文字列の変換処理
    return string
}

上記のコードでは、ParametersとReturnsの後にコロン(:)が抜けているため、ドキュメント生成時にエラーが発生します。

このようなミスは、ドキュメントコメントの書き方をしっかりと理解し、確認作業を怠らないことで避けることができます。

●ドキュメントコメントのカスタマイズ方法

Swiftのドキュメントコメントは、そのままでも非常に有効ですが、さらにカスタマイズを行うことで、より詳細な情報や、見た目のカスタマイズが可能になります。

ここでは、カスタマイズの方法を2つのサンプルコードを交えて徹底的に解説します。

○サンプルコード9：カスタムテーマの適用方法

このコードでは、Jazzyなどのドキュメントジェネレータを使用して、独自のテーマを適用する方法を示しています。

JazzyはSwiftやObjective-Cのドキュメントを生成するためのツールで、独自のテーマを利用して、見た目を変更することができます。

# Jazzyのインストール
gem install jazzy

# 独自テーマの適用
jazzy --theme [テーマのパス]

上記のコマンドを実行することで、指定したテーマを使用して、ドキュメントを生成することができます。

テーマの詳しいカスタマイズ方法は、Jazzyの公式ドキュメントを参照してください。

○サンプルコード10：独自のタグを作成する方法

Swiftのドキュメントコメントには、標準で用意されているタグ（- Parameters, - Returnsなど）がありますが、独自のタグを追加することも可能です。

このコードでは、独自のタグを作成し、それをドキュメントコメントに適用する方法を解説しています。

/**
  文字列を反転させる関数
  - Parameters:
    - string: 反転させる文字列
  - Returns: 反転させた文字列
  - Note: この関数は、空白文字を含む文字列にも使用できます。
*/
func reverseString(string: String) -> String {
    return String(string.reversed())
}

上記のコードでは、- Note:という独自のタグを使用して、追加の情報を記述しています。

このように、独自のタグを使用することで、より詳細な情報や、特定の情報を強調することができます。