Takahiro Octopress Blog

-1から始める情弱プログラミング

jazzyを使って、Swiftで書いたプロジェクトのリファレンスを自動生成しよう！

jazzyとは

さて、本日はjazzyについて書こうと思います。
jazzyはSwiftで書いたプロジェクトのリファレンスを自動で生成できるツールです。
最近、熱いMobile DatabaseであるRealmと同じチームが開発しているようです。
今のところ、他に良さそうなツールはないんじゃないでしょうか？

兎にも角にも、早速使ってみることにします。

jazzyのインストール

jazzyのインストールは簡単です。
下記コマンドを実行してください。

sudo gem install jazzy

jazzyのコマンド

jazzy -hを実行してコマンドを確認してみましょう。
下記のような結果が得られるはずです。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49

Usage: jazzy

Options
  -o, --output FOLDER              Folder to output the HTML docs to
  -c, --[no-]clean                 Delete contents of output directory before running.
                                   WARNING: If --output is set to ~/Desktop, this will delete the ~/Desktop directory.
      --[no-]objc                  Generate docs for Objective-C.
      --umbrella-header PATH       Umbrella header for your Objective-C framework.
      --framework-root PATH        The root path to your Objective-C framework.
      --sdk [iphone|watch|appletv][os|simulator]|macosx
                                   The SDK for which your code should be built.
      --config PATH                Configuration file (.yaml or .json)
                                   Default: .jazzy.yaml in source directory or ancestor
  -x arg1,arg2,…argN,              Arguments to forward to xcodebuild
      --xcodebuild-arguments
  -s FILEPATH,                     File generated from sourcekitten output to parse
      --sourcekitten-sourcefile
      --source-directory DIRPATH   The directory that contains the source to be documented
  -e, --exclude file1,file2,…fileN Files to be excluded from documentation
      --swift-version VERSION
  -a, --author AUTHOR_NAME         Name of author to attribute in docs (e.g. Realm)
  -u, --author_url URL             Author URL of this project (e.g. http://realm.io)
  -m, --module MODULE_NAME         Name of module being documented. (e.g. RealmSwift)
      --module-version VERSION     module version. will be used when generating docset
      --copyright COPYRIGHT_MARKDOWN
                                   copyright markdown rendered at the bottom of the docs pages
      --readme FILEPATH            The path to a markdown README file
      --podspec FILEPATH
      --docset-icon FILEPATH
      --docset-path DIRPATH        The relative path for the generated docset
  -r, --root-url URL               Absolute URL root where these docs will be stored
  -d, --dash_url URL               Location of the dash XML feed e.g. http://realm.io/docsets/realm.xml)
  -g, --github_url URL             GitHub URL of this project (e.g. https://github.com/realm/realm-cocoa)
      --github-file-prefix PREFIX  GitHub URL file prefix of this project (e.g. https://github.com/realm/realm-cocoa/tree/v0.87.1)
      --min-acl [private | internal | public]
                                   minimum access control level to document
      --[no-]skip-undocumented     Don't document declarations that have no documentation comments.
      --[no-]hide-documentation-coverage
                                   Hide "(X% documented)" from the generated documents
      --head HTML                  Custom HTML to inject into <head></head>.
      --theme [apple | fullwidth | DIRPATH]
                                   Which theme to use. Specify either 'apple' (default), 'fullwidth' or the path to your mustache templates and other assets for a custom theme.
  -t, --template-directory DIRPATH DEPRECATED: Use --theme instead.
      --assets-directory DIRPATH   DEPRECATED: Use --theme instead.
  -v, --version                    Print version number
  -h, --help [TOPIC]               Available topics:
                                      usage   Command line options (this help message)
                                      config  Configuration file options
                                   ...or an option keyword, e.g. "dash"

ヘルプを見て頂ければ、なんとなく概要をつかめると思いますが、特に重要なものを説明します。

  1. -o FOLDER
    リファレンスの出力場所を指定するコマンドです
  2. --min-acl [private | internal | public]
    リファレンスに出力するプロパティおよびメソッドの最低アクセス権限
    例えば、--min-acl publicを指定した場合、privateやinternal指定されたプロパティやメソッドはリファレンスに出力されません。
  3. --skip-undocumented
    ドキュメントコメントが書かれていないプロパティやメソッドはリファレンスに出力しません。
  4. --author AUTHOR_NAME
    リファレンスに開発者を明記します。
  5. --author_url URL
    リファレンス上に表記される開発者名にURlリンクを付与します。

Swift2.0以降でのドキュメントコメントの書き方について

Swift2.0以降でのドキュメントコメントの書き方を見ていきます。
jazzy を使うことを前提にした書き方のみ記述します。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52

import UIKit

/**

UIViewControllerを継承したViewControllerクラス
  
*/
class ViewController: UIViewController {

  // MARK: Properties
  /// 文字列を格納するためのサンプル変数
  var sampleParam1:String?
  /// 数値を格納するためのサンプル定数
  let sampleParam2:Int = 0

  <省略>
  
  // MARK: Method
  /**

 ログを出力するメソッド
         
 - parameter message: ログ出力したいメッセージ
                 
 */
  func sampleMethod(message: String) {
      print(message)
  }

  /**

 trueフラグを返すメソッド
         
 - returns: trueフラグ
                 
 */
  func sampleMethod2() -> Bool {
      return true
  }

  /**

 メッセージを生成するメソッド
          
 - parameter message: 生成したいメッセージの一部分
 - returns: 生成したメッセージ

 */
  func sampleMethod3(message:String) -> String {
      return "生成したメッセージ： \(message)"
  }
}

ポイントは、

  • クラス名にドキュメントコメントを必ずつけること
  • メソッドのDescriptionとParameterもしくはReturnとの間に1行をあけること
  • :param:や:returns:といった古い書き方をしないこと

です。

上記ポイントを踏まえた上で、
jazzy --min-acl internal --skip-undocumented -o jazzy_doc --author Takahiro --author_url https://grandbig.github.io/
を実行してみましょう。
オプションは必要に応じてつけてください。

結果、下図のようなリファレンスが作成されます。

トップページ
こちらはトップページです。

クラスの説明
続いて、クラスを選択した際に表示されるクラスの説明ページ

クラスのプロパティの説明
各プロパティを選択すれば、その説明が表示されます。

クラスのメソッドの説明
各メソッドを選択すれば、その説明が表示されます。

いかがだったでしょうか？
リファレンスは第三者にソースコードを説明する上でも非常に重要なものです。
初めから書式ルールに沿ってコードを書いておけば、自動生成ツールで速攻リファレンスを作れますので、ぜひぜひ把握しておきましょう。

と言ったところで本日はここまで。

Comments