[iOS][Swift] 「Jazzy」を使ってSwiftのソースファイルからドキュメントを生成する






jazzy is a command-line utility that generates documentation for Swift or Objective-C




  • macOS High Sierra バージョン 10.13.3
  • Xcode Version 9.2 (9C40b)
  • Swift 4
  • Jazzy 0.9.1
  • CocoaPods 1.3.1

ここではあるiOSアプリを作成していて、ライブラリ管理にはCocoaPodsを使用しているとしましょう。 プロジェクト名は今回「JazzySample」としました。 CocoaPodsでライブラリをインストールすると、以下のようにxcworkspaceファイルが生成されているでしょう。



import Foundation

/// ユーザーのリポジトリ
class UserRepository {

    /// IDを指定してユーザーを取得する。
    /// - Parameter identifier: ユーザーID
    /// - Returns: ユーザー
    func find(byIdentifier identifier: String) -> User {
        // TODO: impl
        return User(identifier: "1", name: "kato")

    /// プライベート関数
    private func pFunc() {
import Foundation

/// ユーザー
struct User {

    /// ID
    let identifier: String

    /// 名前
    let name: String




[sudo] gem install jazzy

jazzy -h でオプションの説明が見れる

jazzyには非常に豊富な実行オプションがあるため、 jazzy -hコマンドを実行して、自分の環境に関係ありそうなオプションをざっと眺めておくといいかと思います。

Usage: jazzy

    -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.
                                     Hide declarations in the specified language. Given that generating Swift docs only generates Swift declarations, this is only really useful to display just the Swift declarations & names when generating docs for an Objective-C framework.
        --config PATH                Configuration file (.yaml or .json)
                                     Default: .jazzy.yaml in source directory or ancestor
    -x arg1,arg2,…argN,              Arguments to forward to xcodebuild
    -s FILEPATH,                     File generated from sourcekitten output to parse
        --source-directory DIRPATH   The directory that contains the source to be documented
    -e filepath1,filepath2,…filepathN,
        --exclude                    Source file pathnames to be excluded from documentation. Supports wildcards.
        --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
        --documentation GLOB         Glob that matches available documentation
        --abstract GLOB              Glob that matches available abstracts for categories
        --podspec FILEPATH           A CocoaPods Podspec that describes the Swift library to document
        --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)
        --disable-search             Avoid generating a search index. Search is available in some themes.
        --skip-documentation         Will skip the documentation generation phase.
        --min-acl [private | fileprivate | internal | public | open]
                                     minimum access control level to document
        --[no-]skip-undocumented     Don't document declarations that have no documentation comments.
                                     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.
        --use-safe-filenames         Replace unsafe characters in filenames with an encoded representation. This will reduce human readability of some URLs, but may be necessary for projects that expose filename-unfriendly functions such as /(_:_:)
    -t, --template-directory DIRPATH DEPRECATED: Use --theme instead.
        --assets-directory DIRPATH   DEPRECATED: Use --theme instead.
        --undocumented-text UNDOCUMENTED_TEXT
                                     Default text for undocumented symbols. The default is "Undocumented", put "" if no text is required
    -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"



jazzy --min-acl internal \
-c  \
-o docs \
--author kato  \
--author_url https://dev.classmethod.jp/ \
--module JazzySample \
--xcodebuild-arguments -workspace,JazzySample.xcworkspace,-scheme,JazzySample


  • min-ac
    • minimum access control level。[private | fileprivate | internal | public | open]
    • ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
  • c
    • 実行前に出力先フォルダをクリーンする。
  • o
    • ドキュメント出力先フォルダの指定
  • author
    • 著者
  • author_url
    • 著者のURL
  • module
    • ドキュメント化するモジュールの名前
  • xcodebuild-arguments
    • xcodebuildへ渡すパラメータ。カンマ区切りで指定する。


おぉ、ちゃんとドキュメント生成されてますね〜!! 今回はmin-acinternalを指定したのでprivateな関数はドキュメントに含まれていないですね。すごい。


上述のようにコマンドラインでオプションを指定して実行できますが、別途オプションを記載したyamlファイルを用意して実行することもできます。 指定するオプションが多い場合や、設定ファイルもgit等で管理したい場合はyamlファイルを使用した方が良いでしょう。 デフォルトで、.jazzy.yamlというファイルを用意しておけば設定を読み込んでくれるようになっています。


# minimum access control level。[private | fileprivate | internal | public | open]
# ここで指定したレベル以上がドキュメント化される。別の言い方をすると、ここで指定したレベルより厳しいレベルについてはドキュメント化されない。
min_acl: internal

clean: true

# ドキュメント出力先フォルダ
output: docs

# 著者
author: kato

# 著者のURL
author_url: https://dev.classmethod.jp

# ドキュメント化するモジュールの名前
module: JazzySample

# xcodebuildの引数
xcodebuild_arguments: [-workspace,JazzySample.xcworkspace,-scheme,JazzySample]



簡単にドキュメント生成できて、オプションも豊富で、設定ファイルに記述できて、もうめちゃめちゃ便利ですね。 生成されるモジュールが複数あるプロジェクトの場合はモジュール名を忘れずに指定するようにしてください。 うまくドキュメントが生成されない場合は、まずxcodebuild単体で実行してみるといいと思います。