Table of Contents

Xcodeでプログラムを書いているとき、Quick Helpを参照することが頻繁にあります。普段の開発シーンでも、Quick Helpには、かなり助けられています。今回は、プログラムの見通しを良くしたり、プログラムを安全に使えるようにしたり、他の開発者や未来の自分自身を助けるために使える、便利なDocコメントやアノテーションをまとめたいと思います。

Xcode Quick Help #

XcodeのエディタのQuick Helpで表示できるテキスト。Calloutsと呼ばれるマークアップの指定ワードのようなもので、説明を追加していきます。使える表現は、Documentation ArchiveのMarkup Formatting Reference「Markup Functionality」がよくまとまっています。

ここからは、Formatting Quick HelpとInserting Calloutsを参考にしながら、一気にまとめます。

Quick Help Sections #

ざっくり以下のような感じ。

/// Summary（簡潔な説明を書く）
///
/// Discussion（追加の説明があれば書く）
///
/// - Callouts ※Parameter・Parameters・Throws・Returns「以外の」もの
///
/// - Parameters:
/// - Throws:
/// - Returns:
func someFunction(p1: Hoge) throws -> Fuga {
    // 関数本体
}

/// Summary（簡潔な説明を書く）
///
/// Discussion（追加の説明があれば書く）
let hoge: Hoge

Parameters・Parameter #

/// - Parameters:
///   - p1: <#p1 description#>
///   - p2: <#p2 description#>

引数が2つ以上ある場合に使用する。なお、1つしかない場合は、- Parameter <#変数名#>: <#説明#>のような書き方をする。

ちなみに、 <#p1 description#> をXcodeにコピペすると、プレースホルダになる。予めコードスニペットを登録しておくと、とても便利。

Throws #

/// - Throws: <#説明#>

メソッドからスローされるエラーを指定する。 1つのメソッドのドキュメントに、1つだけ指定できる。

Returns #

/// - Returns: <#説明#>

メソッドの返り値を指定する。 1つのメソッドのドキュメントに、1つだけ指定できる。

上記以外のCallouts #

ドキュメントを読む限りだと、以下のCalloutsに「使い方」があるわけではないようです。せいぜい強調して表示されるデリミタがあるよ程度の扱いっぽいです。 Quick Helpで表示しなくても、Docコメントの部分で理解しやすくする程度の気持ちで、書いておくと良さそうです。

以下のCalloutsは、Quick HelpのDescriptionの次の項目として表示されます。記載するときの基本形は、下のような感じ。同じものを複数つけても良いらしいです。

///
/// 単数形のときの書き方
/// - <#Calloutのキーワード#>: <#完結な説明。#>
/// <#説明の続き（あれば）。#>
///
/// 複数形のときの書き方
/// - <#Calloutのキーワード（複数形）#>:
/// <#項目1#>
/// <#項目1の説明（あれば）#>
///
/// <#項目2#>
/// <#項目２の説明（あれば）#>

したがって、使えるものを列挙するにとどめます。

※以下で出てくる「シンボル」は、関数や変数全般を指す。

Attention（シンボルの利用者に対して、強調する情報を表示）
Author（シンボルの作成者を表示）
Authors
- 複数パターンの記法
Bug（シンボルのバグを表示）
Complexity（関数やメソッドのアルゴリズムの複雑さを表示）
Copyright（著作権情報の表示）
Date
Experiment（実験や検証について）
Important（ユーザーが実行しようとしているタスクに悪影響を与える可能性のある情報を強調表示。Attentionのほうが軽そう）
Invariant（不変のものについて）
Note（メモや補足程度か。Remarkとも似ている気がする）
Postcondition（シンボルの実行の完了時に保証されている状態について書く。変数が変わっている・変わっていないなど）
Precondition（シンボルが機能するために必要な状態について書く。変数がバリデート済み・フラグが立っていることなど）
Remark（関心事に対する言及か。Noteとも似ている気がする）
Requires（使い方はPreconditionを見てくださいとのこと。エイリアスかよ）
SeeAlso（他の情報について）
Since（いつから使えるようになったかを書く、日付、フレームワークのバージョン、オペレーティングシステムのバージョンなど）
ToDo（未完了や更新が必要なことについて）
Version
Warning

ここまでの参考サイト #

https://swift.org/documentation/api-design-guidelines/ https://qiita.com/taji-taji/items/6ac9a6e508d53bc1ba42 https://qiita.com/Todate/items/819618dbb56e61d97453

ジャンプバーで使用可能なアノテーション #

Xcode11以降は、エディタ右側のミニマップにも反映されるようになった。

MARK #

見出しを表示できる。

見出しのみ #

// MARK: 見出しのみ

区切り線の下に見出し #

// MARK: - 区切り線の下に見出し

区切り線の上に見出し #

// MARK: 区切り線の上に見出し　-

区切り線を示す - は、以下のFIXME, TODOでも使用できる。

TODO #

あとでやることを残す。

// TODO:

FIXME #

バグが残っていたり、修正したいことを書く。

// FIXME:

ここまでの参考サイト。 #

https://qiita.com/chino_tweet/items/ef9a0258615605404b14

おわりに #

XcodeのQuick Helpで使えるコメントのフォーマットをまとめました。使えるCalloutsもさほど多いわけではないので、使えるものが一通りわかってしまえば、あとは思い出しながら使っていけそうです。