前提

この記事では、コメントのフォーマットについて説明が主旨であるので、
記事中のコードは、適当で価値ないコードなので、参考にしないでください。

どういった感じになるの？

書き方を習って書くことで、下記のようになります。

どうやって書いてるの？

ほとんどのMarkdown記法を使えます。

定義箇所

public struct AuthJwt {
    var alg:String
    var typ:String
}
public enum AuthNError : Swift.Error {
    case invalidJwt(msg:String)
}

/**
 # ユーザ認証ユースケース(by protocol)
 */
public protocol AuthNUseCase {
    /**
     ## トークン取得

     認証用トークンをOPサーバーにリクエストをPOSTします.

     - precondition: 
       - JWTは検証済み.
       - 最初にこのメソッドを呼ぶこと.
     - postcondition : 戻り値の検証をすること.
     - requires:
       - 通信環境が確保されていること.
       - OP側と鍵の共有されていること.
     - note:
       - [JWTについて](https://www.rfc-editor.org/info/rfc7519)
     - warning: 
       - メインスレッド上で通信処理を行う.**スレッド管理については呼び出し責任とする.**

     ---
     - parameter jwt: 認証用JWT
     - returns: RSA526形式トークン
     - throws: AuthNError
     ```
         let authN = AuthNUserCaseImpl()
         authN.fetchToken(jwt:AuthJwt(alg:"HS256", typ:"JWT"))
     ```
     */
    func fetchToken(jwt:AuthJwt) throws -> String?
}

/**
 ## ユーザ認証ユースケース(by struct)
 */
struct AuthNUserCaseImpl : AuthNUseCase {
    /**
     # ほげほげ
     */
    func fetchToken(jwt: AuthJwt) -> String? {
        return nil
    }
}

呼び出し元

let authN:AuthNUseCase = AuthNUserCaseImpl()
let token = try! authN.fetchToken(jwt: AuthJwt(alg: "HS256", typ: "JWT"))

めんどうじゃない？

はい。正直全てのメソッドやクラスをこのように書くのは、億劫ですね。
「コードがドキュメントです」とは言わないけど、メンテナンスコストが恩恵を上回っても本末転倒ですし。

道具は振り回されずに使いまわす

どこまで書き込むかどうかはチーム内運用によって決めてもらえればと思います。

例えば

「共通コードの公開I/Fに関しては、事前条件、事後条件、サンプルコードは必須にしよう」など決めておくことで

使う側／１週間後の自分／新人からしたら

やりたいことが分かりやすい
作った人以外でもメンテナンスしやすい
新人でもコードレビューを使って先輩に斧を投げれる
新人に陥りがちな「作り終わったら違う目的を達成」をセルフレビューできる

注意事項

注意ってほどでもないですが、いくつか挙動にルールがありました。

書いた順番に表示されない
TODO: FIXME: などは動かない

書いた順番に表示されない

例えば紹介したコードでは、サンプルコードを一番最後に記述していますが、Quick Helpだと最初に記述していた引数や例外、戻り値などが下の方に表示されます。

TODO: FIXME: などは動かない

ブロックコメントだとそういう仕様なので別仕様ですがコメントで

//TODO: hogehoge

と書けば

と表示されますが、コメント内に

/**
- note:
  - [JWTについて](https://~~~~)
  - TODO: hogehgoe
*/

とついうっかり箇条書きでTODOを書いてしまいがちですが、書いても反応しません。

この場合は

/**
- note:
  - [JWTについて](https://~~~~)
- TODO: hogehgoe
*/

と記載することで Quick Helpに別枠としてきちんと表示されます。
しかし、一行コメント時と同じエディタ上部のパンクズリストには出ません。

参考

他の詳細は下記にまとまってあります。

Markup Formatting Reference

コメントをMarkdown形式で書いてXcodeのQuick Helpとチーム仲を豊かにする

前提