Swiftのドキュメントコメント

メソッドに適切なコメントを書こうと思っても、Option+Command+/で出せるParametersやReturns以外は何があったかすら結構忘れがち。

なので、コピペ用にまとめて置こうと思った次第。

import Foundation

/// オブジェクトのサンプル
class SampleObject {

    /// サンプルメソッド
    ///
    /// - Attention: Watch out for this!
    /// - Author: Tim Cook
    /// - Authors:
    ///   John Doe
    ///   Mary Jones
    /// - Bug: This may not work
    /// - Complexity: O(log n) probably
    /// - Copyright: 2016 Acme
    /// - Date: Jan 1, 2016
    /// - experiment: give it a try
    /// - important: know this
    /// - invariant: something
    /// - Note: Blah blah blah
    /// - Precondition: alpha should not be nil
    /// - Postcondition: happy
    /// - Remark: something else
    /// - Requires: iOS 9
    /// - seealso: [Apple web site](www.apple.com)
    /// - Since: iOS 9
    /// - Todo: make it faster
    /// - Version: 1.0.0
    /// - Warning: Don't do it
    ///
    /// - Parameters:
    ///   - paramA: パラメータAの説明
    ///   - paramB: パラメータBの説明
    /// - Returns: 戻り値の説明
    func sampleMethod(paramA: String, paramB: String) -> String {
        return paramA + paramB
    }

}

jazzyでドキュメントとして出力すると、こんな感じになります。

ながっ。

コメントを書くのはいい事だけど、何事もほどほどに。

参考

https://qiita.com/y-some/items/8bc06567eee18dfeafbb
https://useyourloaf.com/blog/swift-documentation-quick-guide/