Swift 2のドキュメントコメントの書き方(JavaDoc的なやつ)

公開日: : 最終更新日:2016/02/10 iPhoneアプリ開発

20160122-095132.jpg

コード補完時やoptionクリック時などに説明が出てくるようにする「ドキュメントコメント(Javaで言うJavaDocみたいなやつ)」の書き方について解説したいと思います!

    

スポンサード リンク

ドキュメントコメント(文書化コメント)

/** から始まるコメント、または /// で始まる行末までのコメントがドキュメントコメント(文書化コメント)として扱われます。

/**
 コメント
 */
/// コメント

    

段落

空白行によって段落を表現できます。

段落1

段落2

段落3

    

ソースコード

行の先頭に空白4つ、あるいは前後行を「“`(バッククォート3つ)」で囲うとコード行としてグレーの四角で囲われます。

``` 
let b = 234 
```

    

引数

以下のいずれかの書式で、引数に関する情報を書くことができます。

- parameter 引数1: 引数1に関する説明
- parameter 引数2: 引数2に関する説明
- parameters:
    - 引数1: 引数1に関する説明
    - 引数2: 引数2に関する説明

    

返り値

以下の様な書式で、返り値に関する情報を書くことができます。

- returns: 返り値に関する説明

    

エラー

以下の様な書式で、エラーがthrowされる場合の情報を書くことができます。

- throws: エラーがthrowされる場合の説明

    

見出し

行の先頭に#を置くことで、その行を見出しにできます。

# 見出し1

## 見出し2

### 見出し3

    

箇条書き

“-“, “+”, “*” を使うと箇条書きを表現できます。

- 項目1
- 項目2
- 項目3

    

太字・斜体

「**文字列**」「__文字列__」を使うと太字、「*文字列*」「_文字列_」を使うと斜体を表現できます。

**太字**

*斜体*

    

水平線

「—」または「***」で水平線を表現できます。

---

***

    

リンク

[リンク文字列](リンク先のアドレス) で、リンクを表現することができます。

[卵は世界である](http://egg-is-world.com)

    

実例

ドキュメントコメントを使った実例を以下に示します。

/// 割り算に関するエラー
enum DivideError : ErrorType {
    /// ゼロ除算
    case ZeroDivide
}


/**
 割り算を行う
 
 - parameter num1: 割られる数
 - parameter num2: 割る数
 
 - throws: 割る数が0だった場合にエラー
 
 - returns: 割り算の結果
 */
func divide(num1 num1: Int, num2: Int) throws -> Int {
    guard num2 != 0 else {
        throw DivideError.ZeroDivide
    }
    
    return num1 / num2
}

    

@akio0911はこう思った。

ドキュメントコメントをキッチリ入れておくと、コード補完時などに説明が出てくるのでコードが書きやすく&読みやすくなると思います!

ちなみにSwift 2のコメントに関しては以下の書籍に詳しく載っているので、気になる方は読んでみると良いかもです。

    

この記事が気に入ったら「いいね!」しよう

follow us in feedly

Feedlyで最新記事を購読

Twitterで更新情報をゲット!

LINEでご感想・ご要望お送りください!
(スマホでLINEを起動 > 友だち追加 > QRコード)

関連記事

20150525-224340.jpg

【Swift】クロージャをメソッドや関数の引数として渡す方法

Swiftでメソッドの引数としてクロージャを渡す方法について解説したいと思います。     

記事を読む

I20150808-104713.jpg

【Xcode】シミュレーターリストの表示がおかしくなった時の解決方法

Xcodeのシミュレーターリストの表示が、上のスクリーンショットのようにおかしくなってしまっ

記事を読む

I20160209-123839.jpg

【Swift】プロパティのsetとgetには異なるアクセス修飾子を指定できる

Swiftでは、プロパティのセッタ(set節)とゲッタ(get節)に異なるアクセス修飾子

記事を読む

I20160201-112159.jpg

ライブラリ管理ツールCarthageのCartfileの書き方

iOS(Cocoa)ライブラリ管理ツール「Carthage」で使用するCartfileの書き方を

記事を読む

20160802-232454.jpg

【Xcode 7】メソッドがどこから呼びだされているかを調べる方法

Xcode 7で、メソッドがどこから呼び出されているのか調べる方法を紹介します!     方法

記事を読む

I20160409-211651.jpg

Xcode 7.3の新機能についてまとめてみた

2016年3月22日にXcode 7.3がリリースされましたが、自分が知らない機能があるかもしれ

記事を読む

I20160102-131507.jpg

Swift 2の文法が分かるオススメ本「詳解 Swift 改訂版」

Swift文法書の定番とも言える、荻原 剛志さんの「詳解 Swift」。 Swiftの文法をキ

記事を読む

I20151201-120520.jpg

【Swift 2】switch内にてguardでbreakする

Swift 2のguard内ではreturnしないと文法エラーとなりますが、実はswitch

記事を読む

20141225-223049.jpg

【Xcode6】Auto Layoutで制約のFirst ItemとSecond Itemを逆にする方法

一度追加した制約のFirst ItemとSecond Itemを入れ替える方法について紹介します

記事を読む

エディタのショートカット・Auto Layout・ブレークポイントに関する詳しい解説も!「Xcode5徹底解説」

著者の@es_kumagaiさんより献本御礼。iOSアプリ開発に用いるツール「Xcode 5」の

記事を読む

I20170521-225453.jpg
東京駅八重洲口の「羊肉酒場 悟大」で網焼きジンギスカンを頂きました!

ゆうせいさんと株式会社 大庄さんからご招待頂き、悟大withサッポ

I20170514-165235.jpg
iPhoneと連携できる体重体組成計「Withings Body Cardio」を使ってます

ジムに通い始めて体脂肪率が落ち始めたのをキッカケに、iPhoneと

I20170507-155440.jpg
【派手髪】ハーレイクイン風の髪色に染めてもらいました

2016年10月20日、ハーレイクイン風の髪色に染めてもらいました

I20170504-173110.jpg
【メンズネイル】東京・新宿のネイルサロンでターコイズのホログラムネイルしてもらった

ネイルネタが1年分くらい溜まっているので、ちょっとずつ書いていこう

I20170502-010117.jpg
SNUGGのライトニングケーブルが耐久性高し。8ヶ月使ってますが断線の気配なし!

iPhoneの充電&転送ケーブルであるLightningケーブルっ

→もっと見る

PAGE TOP ↑