XcodeにおけるDocCドキュメントについて

XcodeにおけるDocCドキュメントについて

Swiftパッケージやフレームワークに関するドキュメントを構築・共有するために、DocCをどのように利用できるかについて確認します。自作のコードや依存しているサードパーティのコードからドキュメントの生成を開始し、Markdownを使用して記述およびフォーマットする方法を紹介します。また、公開を目的としたDocCアーカイブ生成のためのエクスポートのプロセスについても解説します。

リソース
関連ビデオ

WWDC23
- Swift-DocCで充実したドキュメントを作成
WWDC21
ダウンロード

こんにちはVictoriaです AppleのDocumentation Toolsチームのエンジニアです同僚のEthanと共に Xcode 13での新しいドキュメント機能を紹介しますワークフローに適した新たなドキュメントの読み書き方法で開発の新しい可能性を解き放ちましょう Xcode 13にはSwiftフレームワークとパッケージのドキュメントを構築作成閲覧するための新機能がありますこれによりコードを記述しながら Swiftの依存関係をすべて確認できるドキュメント主導の強力な開発が可能になりますこの機能はXcodeのDeveloper Documentation 内のプラットフォームライブラリにありますこの動画では Xcode 13のドキュメント機能の概要説明あなたが使用している Swiftフレームワークとパッケージのドキュメント作成方法 Xcode13を使用して優れたドキュメントを作成する方法そしてXcode13でドキュメントを共有する方法を説明します初めに私が個人的にドキュメントの新機能に期待している点をお話します誰もが経験があるはずです使用したい新しいフレームワークやパッケージをコードに実装する際は何が含まれているかすべて把握しなければなりませんここで登場するのがXcode 13です Xcodeにはドキュメントとコード用のコンパイラが付属しており SwiftフレームワークとパッケージのドキュメントをすべてXcode内でビルドおよび表示できます AppleではこれをDocCと呼んでおりドキュメントの読み取りと書き込みの方法を強化するためにXcode全体に実装されています DocCは事後に実行される単なるドキュメントコンパイラではありません Xcodeを補完する完全に統合されたドキュメント環境ですクイックヘルプにドキュメントが表示されるリッチなライブ環境ドキュメントを全体に結び付けられる優れたコード補完さらに統合されたDeveloper Documentationウィンドウが完全なドキュメント機能を提供します作成済みのドキュメントを共有して XcodeやWebで表示するなどの簡単なオプションがあります DocCに関する詳細については WWDC 2021の他の動画もご覧ください DocCはXcodeと Swiftの機能を活用しフレームワークまたはパッケージ内のパブリックAPIの全体像を提供します APIが単独でではなくどう連携可能かを説明する機能を備えた優れたリファレンスドキュメントを作成できますそれだけにとどまらず DocCは他にも多くのことを可能にします DocCを使ってドキュメントを作成する新たな方法を他に２つ紹介します記事を使用するとフレームワークの背後にある全体像をユーザーに説明しフレームワーク内の個々のアイテムをまとまりのあるストーリーと結び付けることができますチュートリアルではフレームワークを使ったプロジェクトの作成方法をステップ別に説明していますユーザーにフレームワークに関するガイド付きの説明が提供されるためリファレンスドキュメントや記事よりもはるかに深い理解が可能です
こうしたオーサリング体験はマークダウンの威力とシンプルさを活用および拡張してコードを書くのと同じくらいスムーズなドキュメントのオーサリングを実現しますソースコード以外の記事やチュートリアルを含むドキュメントカタログの作成について詳しく知りたい場合は今年のWWDCのこれらの動画をご覧ください
また今年後半にオープンソースとして DocCがリリースされます構築したドキュメントアーカイブを Web上でホストできる Web Appと一緒に使用することで Xcodeの外部でも新しいドキュメントワークフローを利用できます Xcode 13の新しいドキュメント機能を理解したところで XcodeのDocCを使用してドキュメントを作成する方法について説明しますまずはその仕組みから見ていきましょうドキュメントを作成するためにXcodeはフレームワーク又はパッケージをビルドしコンパイルされたアーティファクトと一緒にパブリックAPIに関する情報を保存するようコンパイラーに要求しますパブリックAPIの情報がDocCに渡されるとソースコードの外部で記述された記事やチュートリアルなどのドキュメントカタログと組み合わせてコンパイルしたドキュメントを含む最終的なアーカイブを作成しますドキュメントカタログとドキュメントの整理についての詳細は Xcodeセッションの動画「XcodeにおけるDocCドキュメントのレベルの向上」をご覧下さい。 DocCとXcodeのビルドシステム統合のおかげでこのプロセスはターゲットが依存する全Swiftのフレームワークとパッケージに対して繰り返されますこれにより関連するドキュメントをすべて１箇所に集約できます日々のドキュメント業務ではどう役立つのでしょうか？ Xcode 13でSwiftフレームワークとパッケージのドキュメントを作成する方法は３つあります
ドキュメントをオンデマンドでビルドする場合ドキュメントをコンパイルし読み込むための新機能 “Build Documentation”を使用しますまたSwiftフレームワークで作業していてドキュメントを常にプレビューしたい場合コンパイルする度にドキュメントをビルドできる新しいビルド設定がありますコマンドラインとCIのニーズに対してxcodebuildにはドキュメントをビルドできる新しいコマンドがあり “Build Documentation”と同じビルドを実行しますがコマンドラインでxcodebuildを使用しますドキュメントワークフローの自動化に関する詳細は同僚のデイビッドによる動画「DocCドキュメントのホストと自動化」をご覧ください。実際の例で見てみましょう。私のチームメートはSlothCreator という名のパッケージを使用していますナマケモノのカタログ化とカスタマイズが目的ですこれがXcode 13でどう機能するかを見てみましょう Slothyと名付けたこのAppをセットアップしたのでナマケモノをカスタマイズしプレビューできます Appの依存関係としてSlothCreatorを設定しました提供されるAPIについて詳しく知りたいので “Product”メニューを開いてみましょう
次に“Build Documentation”を選択します
このように “Developer Documentation”ウィンドウが開き “Navigator”で Slothyプロジェクトと作業中の SlothCreatorパッケージを展開して概要を確認できます SlothCreatorの概要をメインビューにロードします下にスクロールすると使用可能なタイプとプロトコルが表示されます
ここにHabitatというタイプがありますクリックしてページを読み込みましょう
詳しい情報が書いてありますが他にも情報が記述されている場所があるかもしれません上部の検索欄でHabitatを検索します
いくつかの場所で記載があるようです “睡眠”メソッドをクリックしてドキュメントを開きましょう
これは睡眠メソッドに特化したページですがどのタイプに属するのでしょうか？ウィンドウ上部のジャンプバーから “ナマケモノ”タイプに属することがわかります
ナマケモノをクリックするとプルダウンメニューが現れ再度クリックするとこのタイプのドキュメントが開けますこれらのAPIの使い方がわかってきましたねここまでは SlothCreatorのドキュメントを使って説明しましたもう一度おさらいしましょう同僚のEthanが Xcode 13の新機能を紹介し優れたドキュメントの作成方法を説明します Ethan お願いしますありがとうVictoria ドキュメントの作成と閲覧に関する Xcode13の高度な機能を学んだところで DocCを使用してさらに優れたドキュメントを作成するための秘訣を紹介します
DocCはソース内ドキュメントの利点を中心に設計されていますドキュメントをコードと一緒に書くことで既存の開発ワークフローとの統合が便利で簡単になります
宣言にドキュメントを追加するにはそのすぐ上に特別なコメントを書きますこれによりコードの変更があってもドキュメントは同期された状態を維持しますもちろんgit diffのような既存のテキストベースのツールにも対応します
今後コードベースを管理する人に追加のコンテキストを提供するためソースコードに注釈を付けることもあるでしょう Swiftや他の多くの言語の場合２つのスラッシュの後にコメントを記述しますコメントを書くことで将来の管理者がコードを理解しやすくなり生産性が上がります今すぐフレームワークの使用者をサポートしたい場合はどうでしょう？そのためにドキュメントにコメントを書くのです３つのスラッシュで始まるコメントを書くことにより Swiftドキュメントコンパイラにコメントをそのすぐ下の宣言に関連付けるように指示できますコメントはシンボルのコンパイル済みドキュメントページに含まれフレームワークをインポートする全員がアクセス可能ですブロックスタイルのコメントを使用する場合は開始区切り文字に追加のアスタリスクを含めるだけでそのスタイルのコメントを作成できます実際の動作を見てみましょう Victoriaが話した通りAppleはここ数ヶ月 SlothCreatorフレームワークの開発を行っています SlothCreatorはナマケモノのカタログ化とカスタマイズが可能なSwiftパッケージです SlothCreatorの開発者としてユーザーがフレームワークを簡単に使い始められるように私が書いたコードベースの部分にドキュメントコメントを追加しています特にSlothCreatorのすべてのパブリックAPIが十分にドキュメントされるようにしたいと思っていますこのフレームワークをインポートする全員がアクセスできるのはこれらのAPIだからです同じ理由でDocCはフレームワーク内のパブリックシンボルとオープンシンボルのドキュメントページのみを生成しますドキュメントが必要なSlothCreatorのシンボルはあと少しだけです “Food”構造体から始めましょうまずタイプの宣言の上に３つのスラッシュを追加して
ドキュメントコメントを作成します “ナマケモノが食べれる食べ物”と書きますドキュメントコメントの最初の行はシンボルの要約になりますがディスカッションセクションでさらに情報を追加したいと思います要約の後に改行を追加してからナマケモノが好きな食べ物の種類に関する詳細を追加します DocCはマークダウンを完全にサポートしておりフェンスで囲まれたコードブロック構文を使用してコード例を追加できます
便利でしょう？これはFood構造体に関する追加のコンテクストとなりますドキュメントを再構築して今の状態を見てみましょうマウスを“Product menu”に動かし “Build Documentation”を選択します
Xcodeはフレームワークそのものと一緒に SlothCreatorのドキュメントを再構築します “Build Documentation”を使用したためこのビルドのボタンをクリックすると “Build Documentation”が開き更新されたドキュメントが表示されます Food構造体のページに直接アクセスして追加したばかりのコメントを確認してみましょう幸いなことにXcodeのクイックヘルプ機能でこれが可能になりますクイックヘルプはシンボルのドキュメントの概要をソースエディタで表示します
オプションキーを押して Food宣言をクリックします SlothCreatorのユーザーは自分のコードで Food構造体へのリファレンスをクリックし同じビューを開くことができます先程書いたコメントは要約･ディスカッションセクションにあります概要より詳しく見たい場合はXcode 13の “Open in Developer Documentation”を使用します
マウスを動かしてクイックヘルプの右下の “Open in Developer Documentation”をクリックすると“Documentation”がそのシンボルのページに直接表示されますこのように SlothCreatorでドキュメントされていないシンボルが他に１つありますマウスをXcodeのナビゲーターに動かし Slothファイルを開きアイテムをクリックします下にスクロールすると“Eat”メソッドにドキュメントコメントがいるとわかりますではメソッドをドキュメントするための最善の方法を説明します
同じ方法でメソッドの宣言の上に３つのスラッシュのコメントを追加しドキュメントの概要テキストを追加しますパラメータとして渡されると予想されるものも具体的にドキュメントしましょう
これはパラメータセクションでできますパラメータセクションを追加するには “パラメータ”という単語で始まりメソッドのパラメータ名コロンそしてそのドキュメントが続くマークダウンリストアイテムを記述します似た方法でリターンセクションを追加できます今回はリターンの区切り文字の後にコロンとメソッドが返すものを記述しますメソッドに複数のパラメータがある場合単一のパラメーターの区切り文字から複数のパラメーターの区切り文字に変更しますこれはパラメータ名が親パラメータ区切り文字の子として記述される点以外他のパラメータとほぼ同じように機能します基本がわかったところでナマケモノのEatメソッドをドキュメントしましょう３つのスラッシュで始まるドキュメントコメントを手動で書き込むことで Food構造体をドキュメントするのと同じ方法が使えますしかしより複雑なシンボルをドキュメントするので現在の宣言をドキュメントするのに最適なテンプレートを挿入できる Xcodeの “Add Documentation”機能を利用します
コマンドキーを押しながらメソッドの宣言をクリックしてアクションメニューを開きます次にアクションメニューの “Add Documentation”をクリックするとメソッドのドキュメントテンプレートが使えます
まずメソッドの概要を入力してから食べ物と量のパラメータおよびこのメソッドがｃ返すものを説明します次にコード例とともにディスカッションセクションを追加してドキュメントを完成させます
前回と同様にマウスをProductメニューに移動し “Build Documentation”を選択するとドキュメントを再作成できます
Xcodeは再度フレームワーク自体と共にドキュメントを構築します今回はウィンドウのナビゲーターを使って Sloth構造体に移動します SlothがあるのはこのSlothsトピックグループです Slothページを下にスクロールするとインスタンスメソッドセクションで
メソッドが見つけられ更新したドキュメントもありますメソッドのインプットとアウトプットが非常に明確に定義されておりここにも役立つコード例がありますほぼ完成に近付きましたがまだやるべきことがありますこのドキュメントを読むだけではここで検討する必要のある他のシンボルについてのコンテキストが不十分です SlothCreatorの管理者として読者が次に学ぶべき他のシンボルを集めたいと思います Xcode 13の新機能にドキュメント内のシンボルへの紐付けがありますこれはフレームワークの様々な部分をつなげ合い読者を関連情報へと導くための非常に優れた方法です２つのダブルクォートを用いた構文を使います例を見ていきましょう
先程ドキュメントしたSleepメソッドですがバキューム内に存在しません Sloth構造体には別のプロパティがあります
ナマケモノの現在のエネルギーレベルを表す値があります Sleepを呼び出すことの副作用としてナマケモノのエネルギーレベルが変化することを読者が理解することが重要だと思います
そこでenergyLevelプロパティを参照してメソッドのディスカッションセクションに追加します
Xcode 13以前はプロパティの名前をバッククォートで囲み等幅コードフォントを使用していました現在はダブルクォート構文を使用してリンクを作成できます EnergyLevelへのリンクは非常に簡単でしたなぜならそのプロパティはドキュメントするメソッドの兄弟であり参照する際と同じだからです Swiftのローカル変数であるためリンクを親タイプでさらに修飾する必要はありませんただし異なるタイプの子を参照したい場合はより具体的に書く必要がありますここではHabitat/comfortLevelと書き Habitat構造体の子をリンクしています完成です Eatメソッドのドキュメントにリンクを追加して実際の動作を見てみましょうここに“食べ物を食べる時ナマケモノの…”と書き energyLevelプロパティへのシンボルリンクを書きますクォートを２つタイプし energyLevelと書き始めます Xcodeのコード補完機能により正しいリンクを取得できますこのアイテムを選択します
そしてエネルギーレベルは “食べ物の…によって増加する”と書き Food構造体の子を参照しますここでまた２つのクォートです Foodとフォワードスラッシュそして energyと書きます
今作成した２つのシンボルリンクにより読者がこのメソッドのコンテキストを理解しやすくなるでしょうこれらのリンクはクイックヘルプでも利用可能ですオプションキーを押しながらメソッドの宣言をクリックしクイックヘルプを開きます先程追加したディスカッションセクションには２つのリンクがありますいずれかをクリックすると Documentationウィンドウの参照されたシンボルのページに移動します SlothCreatorのすべてのパブリックAPIについてドキュメントコメントが書けたので次は同僚と共有したり Webで公開したいと思いますこれはXcodeが全ドキュメントビルドの一部として出力するドキュメントアーカイブを介して行えますドキュメントアーカイブにはWeb共有に使用できる単一ページのWeb Appが含まれています詳細は同僚のデイビッドによる動画「DocCドキュメントのホストと自動化」をご覧ください。役立つ内容満載です
XcodeはDocumentationウィンドウからの直接のドキュメントエクスポートとインポートにも対応します実際にやってみましょうウィンドウのNavigatorにマウスを移動し DocumentationからSlothCreatorをエクスポートフレームワークのアイテムにマウスを持っていくとコンテキストメニューアイコンが表示されますクリックするとエクスポートできます
デスクトップに保存しますこれで完了です同僚に送信する準備ができましたアーカイブをダブルクリックすると XcodeのDocumentationウィンドウで開きます私はSlothCreatorをすでに知っているので別のドキュメントアーカイブを開きたいと思いますこのところSlothCreatorにコマンドラインインターフェイスを追加できたらいいとチームで話していましたするとArgumentParserというオープンソースのフレームワークが良いという話になりました ArgumentParserの最新ドキュメントアーカイブがあるので開いてみましょうドキュメントアーカイブをダブルクリックするとこのようにすぐ学習を開始しますドキュメントは長続きする優れたフレームワークの開発において重要ですソースに直接ドキュメントを書くことは便利であると共に大きな力を発揮します DocCが加わった新しいXcode 13なら優れたドキュメントを書くほど様々な形でその恩恵が得られます
WWDCでは他の動画でも新たなレベルのドキュメント方法を紹介しています「XcodeにおけるDocCドキュメントのレベルの向上」ではセッションを中断したところから再開しドキュメントカタログを追加してより適切に整理する方法を説明しています「DocCドキュメントのホストと自動化」では先述の通りドキュメントビルドを既存の継続的設定に統合する方法とドキュメントをオンラインでホストする方法について説明します
フレームワークのより複雑な部分についてステップ別の詳しい説明が見たい場合は「DocCを使ったインタラクティブなチュートリアルの制作」をご覧くださいこの部分に特化した内容となっています
ご視聴ありがとうございました [パーカッション音楽]

// A model representing a sloth.
public struct Sloth {
    // ...
}

10:05 - Writing documentation comments

/// A model representing a sloth.
public struct Sloth {
    // ...
}

10:22 - Writing block-style documentation comments

/** 
 A model representing a sloth.
 */
public struct Sloth {
    // ...
}

11:34 - Documenting the Food struct

/// Food that a sloth can consume.
///
/// Sloths love to eat the leaves and twigs they find in the rainforest canopy as they
/// slowly move around. To feed them these items, you can use the `twig`,
/// `regularLeaf` and `largeLeaf` default foods.
///
/// ```swift
/// superSloth.eat(.twig)
/// ```
public struct Food {
		// ...
}

13:58 - Documenting the Sloth.sleep(in:for:) method

/// A model representing a sloth.
public struct Sloth {
    /// Sleep in the specified habitat for a number of hours.
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}

15:39 - Documenting the Sloth.eat(_:quantity:) method

/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// - Parameters:
    ///   - food: The food for the sloth to eat.
    ///   - quantity: The quantity of the food for the sloth to eat.
    /// - Returns: The sloth's energy level after eating.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}

17:46 - Adding symbol links to the documentation for Sloth.sleep(in:for:)

/// A model representing a sloth.
public struct Sloth {
    /// The energy level of the sloth.
    public var energyLevel: EnergyLevel

    /// Sleep in the specified habitat for a number of hours.
    ///
    /// Each time the sloth sleeps, their ``energyLevel`` increases every hour by the
    /// habitat's ``Habitat/comfortLevel``.  
    ///
    /// - Parameters:
    ///     - habitat: The location for the sloth to sleep.
    ///     - numberOfHours: The number of hours for the sloth to sleep.
    /// - Returns: The sloth’s energy level after sleeping.
    mutating public func sleep(in habitat: Habitat, for numberOfHours: Int = 12) -> Int {
        energyLevel += habitat.comfortLevel * numberOfHours
        return energyLevel
    }
}

18:44 - Adding symbol links to the documentation for Sloth.eat(_:quantity:)

/// A model representing a sloth.
public struct Sloth {
    /// Eat the provided specialty sloth food.
    ///
    /// Sloths love to eat while they move very slowly through their rainforest habitats. They
    /// are especially happy to consume leaves and twigs, which they digest over long periods
    /// of time, mostly while they sleep.
    ///
    /// ```swift
    /// let flower = Sloth.Food(name: "Flower Bud", energy: 10)
    /// superSloth.eat(flower)
    /// ```
    ///
    /// When they eat food, a sloth's ``energyLevel`` increases by the food's
    /// ``Food/energy``. 
    ///
    /// - Parameters:
    ///   - food: The food for the sloth to eat.
    ///   - quantity: The quantity of the food for the sloth to eat.
    /// - Returns: The sloth's energy level after eating.
    mutating public func eat(_ food: Food, quantity: Int = 1) -> Int {
        energyLevel += food.energy * quantity
        return energyLevel
    }
}

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

リソース

関連ビデオ

WWDC23

WWDC21