📝

Xcodeのスニペットでコメントを楽々入力

2022/08/08に公開

ツイッターのTLでコメントの話が盛り上がっていたので自分のXcodeでのコメント入力についてメモしておく。
とは言えそんなに大した話ではなく、ただスニペットに登録しておいて入力しやすくしているだけの話。

Xcodeでコメントをドキュメントにする機能

大抵のIDEにある機能だと思うがXcodeにもコメントを元にドキュメントを作成する機能が備わっている。
例えばfuncの上にsこんな感じにコメントを書く。

    /**
     ラジオボタンをRadioButtonViewのリストの最後に加える
     
     - parameter button: リストに加えるRadioButton.
     
     加えられるRadioButtonには.touchUpInsideのイベント時にupdateButtonsを呼ぶアクションが設定される
     */
    func addRadioButton(_ button: RadioButton) {
        button.addTarget(self, action: #selector(self.updateButtons), for: .touchUpInside)
        self.addArrangedSubview(button)
    }

すると下記のようにXcodeのQuickHelpで関数の情報が確認できる。

マークアップの書式については公式のドキュメントに詳しく説明がある。
https://developer.apple.com/library/archive/documentation/Xcode/Reference/xcode_markup_formatting_ref/index.html

今回はこのコメントをスニペットで簡単に入力できるようにしてみる。

Xcodeでスニペットを設定

まずは下記のコードをXcodeでどこでも良いので入力する。(コピペでも良い)

/**
<#Summay text for documentation#>

- parameter <#parameterName#>: <#Description#>.
- returns: <#Return values#>
- warning: <#Warning if any#>

*/

入力したコードを全てを選択したら右クリックでコンテキストメニューを開いてCreate code snippet...を選択。すると選択したコードを元に新しいスニペットが作成される。

後はスニペットの設定をするだけ。

最初にスニペットの名前を決める。今回はFunc Document Comment。
Summaryはスニペットの説明文。必要なら入力しておく。
LanguageはそのままSwift
PlatformもそのままAll
Completionは文字を少し入力したら候補を出してくれるあれ。ここに入力した文字の一部を少し入力すると候補に出してくれるようになる。今回はfcommentとした。

Availabilityはコードのどの部分を編集中にこのスニペットを有効にするか?を指定する。
All Scopesだと頻繁に候補に出てくるようになって少し煩い。今回はfuncのコメント入力用なのでclass implementationにした。

因みに各項目の選択範囲は下記の様になる。

  • Top Level
    文字通りトップレベル。だけど下記の範囲は含まれない。
  • Class Implementation
    クラス定義のトップレベル。下記の範囲は含まれない。
  • Function or Method
    関数、メソッド定義のトップレベル。下記の範囲は含まれない。
  • Code Expression
    式。下記の範囲は含まれない。
  • Comment ot String
    コメントと文字列。

以上の設定をしたらDoneをクリックすれば設定完了。

クラス定義のトップレベルでfc辺りまで入力すれば候補にfcommentが現れるはず。

これを選択すると一気に下記の様に入力される。

後はそれぞれの情報を関数に合わせて入力する。

入力できたらどこか他からその関数を読んでいるところでカーソルを当ててみよう。QuickHelpに関数の説明が表示される!

参考

今回の話は基本的に下記リンク先の内容ほぼそのまま。
https://stackoverflow.com/questions/27715933/how-to-use-swift-documentation-comments/59838568#59838568

ドキュメントをしっかり用意したい場合は下記の様な情報も。
https://developer.apple.com/documentation/xcode/distributing-documentation-to-external-developers

最後に

QuickHelpに表示されると単純に嬉しいので関数の説明のコメントはどんどんこのスニペットで置き換えている。少し前までは自分フォーマットでチマチマ入力していたのでスニペット最高!

自分の様にOSのアップデートに合わせて年に一回だけアプリのアップデートをするような人には、この程度のコメントでもそこそこ役にたっている。本当、去年の自分が何考えてたのか思いの外忘れているんだよね…

Discussion