読者です 読者をやめる 読者になる 読者になる

euphonictechnologies’s diary

Haskell超初心者の日記です。OCamlが好きです。

follow us in feedly

クールなSwift用ドキュメントジェネレーターjazzyを使った

Swift

Swiftにdoxygenが使えない

Objective-Cしか対応していないことに気づきました。私は愚か者なので1ヶ月前から触ってないSwiftコードについて何も覚えていないことに気づきました。一生懸命思い出そうとするのですが、思い出せるのは初孫の名前ばかり。なのでドキュメントをきちんと書いてドキュメンテーションジェネレータできちんと一式揃えていつでも見えるようにしておかなければなりません。役所勤めが長いので書類は打ち出して手にブカブカのアームカバーをつけて頭を剥げさせて丸いメガネで見る癖があります。

今回のタイトルは「〜ってみた」とかいうタイトルがもういい加減鬱陶しいので素直に使った事実を伝えるタイトルにしました。

完成形

まずは今回の作業の完成品です。

f:id:euphonictechnologies:20150328211353p:plain

なんかいい感じに最近チックな見栄えのナイスなドキュメントが出来上がります。これはChromeで表示したものです。

f:id:euphonictechnologies:20150328211641g:plain

こんな感じでメソッドとかインスタンス変数を押すとニュルッと説明が出ます。何も説明を書いていないので説明が出ません。 #pragma markで書いたメソッドのセグメンテーションも認識してセクションごとにタイトルを付けてくれます。いいですね。

jazzyとは

github.com

これです。クールな感じですね。

インストールします。

$ sudo gem install jazzy
...
8 gems installed

インストール出来ました。インストール中に文字コードのエラーみたいなのがたくさん出ますが、大丈夫みたいなのでとりあえず無視しましょう。

使い方

$ jazzy -h

で使い方が見られます。

基本的にはxcodeprojファイルが有るいわゆるプロジェクトルートのディレクトリでjazzyを実行するだけです。出力先を決めないとめちゃめちゃになりそうなので

$ cd <xcodeprojがある場所>
$ mkdir jazzy_doc
$ jazzy -o jazzy_doc

みたいにしてプロジェクトルートの直下にディレクトリを掘ってそこを出力先に設定して実行します。

$ sudo jazzy -o jazzy_doc
Password:
Running xcodebuild -dry-run
Parsing GameScene.swift (1/46)
Parsing GameManager.swift (2/46)
...
Parsing SettingsViewContoller.swift (45/46)
Parsing AppearanceManager.swift (46/46)
building site
jam out ♪♫ to your fresh new docs in `jazzy_doc`

sudoしないとパーミッションエラーが出るのでsudoつけて実行しました。そうするとjazzy_docにindex.htmlと関連ファイル一式が生成されます。

$ cd jazzy_doc
$ open index.html

で開けます。

Swiftで関数とか変数の説明ってどうやって書くんだっけ?

    /**
        Not yet implemented.
    
        :param: firstParam This is nice parameter to specify.
        :param: secondParam This is bad parameter. I should not have expose this parameter to user of the library, indeed...
        :return: True if you're nice guy, false otherwise.

        - Can use bullet point
        - like this
         - and intended.
          - more.
           -and more
         - good?

        Nice comments, ahan?

        #. Or numbers
        #. like this,
        #. looking good, right?
    */
    func configure() {

    }

f:id:euphonictechnologies:20150328215405p:plain

という感じで、一行目にメソッドの説明と:param::return:を使えばとりあえず問題なしです。-+でブレットポイント、#.が自動連番の数字付きリストです。

結局

私が一番欲しかったクラス相関図は生成されませんでした。バージョンアップに期待という名の他力本願はコードがGithubで公開されている以上21世紀は通用しないと思うのです。ですが、ナイスツール。

Swiftコードのドキュメンテーションの参考になりそうなリンクを載せて今回は筆を置こうと思います。