WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
Meet DocC documentation in Xcode

Meet DocC documentation in Xcode

DocCDocumentationXcodeSwift
元の動画を見る

ハイライト

Xcode 13 は DocC ドキュメント コンパイラを統合し、Swift コード コメントからの API リファレンス ドキュメントの自動生成をサポートし、記事とチュートリアルをサポートし、共有用のドキュメント パッケージとしてエクスポートでき、オープン ソースになる予定です。

主な内容

あなたは Swift フレームワークを維持していますが、ドキュメント化が課題となっています。 Jazzy によって生成されたドキュメントのスタイルは Apple の公式ドキュメントと一致せず、サードパーティに依存するドキュメントがいたるところに散在しています。チームメンバーや外部ユーザーから「この API の使い方」についてよく質問されます。

Xcode 13 の DocC はこの問題を解決します。これは Xcode にネイティブに統合されており、Apple 開発者ドキュメントとまったく同じレンダリング エンジンを使用します。

＃＃詳細

3 つのドキュメント タイプ

（01:29）

DocC は次の 3 つのドキュメント タイプをサポートします。

  1. リファレンス: API リファレンス ドキュメント。コード コメントから自動生成されます。
  2. 記事: フレームワークの全体的な設計と使用法を説明する概念的な記事
  3. チュートリアル: ユーザーにプロジェクトの構築方法を段階的に教えるステップバイステップのチュートリアル

ビルドドキュメント

（04:36）

Xcode 13 では、ドキュメントを構築する 3 つの方法が提供されています。

  1. ビルド ドキュメント メニュー: 手動でビルドして表示する
  2. ビルド設定: コンパイルするたびにドキュメントを自動的にビルドします
  3. xcodebuild: コマンド ライン ビルド、CI に適しています
# コマンドラインからドキュメントをビルド
xcodebuild docbuild -scheme MyFramework

（06:08）

キーポイント:

  • Product > Build Documentation手動ビルド
  • BUILD_DOCUMENTATION_COMPILATION = YES自動ビルド
  • xcodebuild docbuildコマンドラインビルド
  • 依存するフレームワークドキュメントも一緒に構築されます

ドキュメントのコメントを書く

（09:34）

コードからの DocC///注釈抽出 API ドキュメント。

/// Food that a sloth can consume.
///
/// Sloths love fresh leaves, especially from the Cecropia tree.
/// Here's how to create food:
///
///

```swift
/// let leaf = Food(name: "Cecropia Leaf")
///

```
struct Food {
    /// The name of the food.
    let name: String

    /// The energy level this food provides.
    ///
    /// - Parameter quantity: The amount of food consumed.
    /// - Returns: The total energy gained.
    func energy(from quantity: Int) -> Int {
        return quantity * 10
    }
}

（10:05）

キーポイント:

  • ///ドキュメントのコメントをマークします (2 つのスラッシュは通常のコメントです)
  • 最初の行は概要であり、リストと検索結果に表示されます。
  • 空白行の後には詳細な説明が続きます
  • マークダウン コード ブロックは構文強調表示でレンダリングされます。

シンボリックリンク

（17:58）

DocC は、ドキュメント内の他のシンボルへのリンクをサポートしています。

/// When they eat food, a sloth's ``energyLevel`` increases.
///
/// The amount of increase depends on the food's ``Food/energy``.
/// For more details, see ``Habitat/comfortLevel``.
func eat(_ food: Food, quantity: Int) -> Int {
    return food.energy(from: quantity)
}

（17:58）

キーポイント:

  • 二重バッククォート `SymbolName` シンボリックリンクを作成する
  • 同じ種類のシンボルには名前を直接記述します
  • さまざまな種類のシンボルが利用可能TypeName/memberName形式
  • Xcode は、正しいシンボルの選択に役立つコード補完を提供します

Quick Help

（12:44）

コード内のシンボルを Option キーを押しながらクリックすると、クイック ヘルプが表示されます。

  • シンボルの概要と説明を表示します
  • パラメータと戻り値の説明が含まれます
  • シンボリックリンクをクリックしてジャンプできます
  • 下部に「開発者ドキュメントで開く」リンクがあります

（13:22）

キーポイント:

  • Option キーを押しながらクリックすると、クイック ヘルプが起動します
  • ソースコードエディターと呼び出しサイトの両方で利用可能
  • 完全なドキュメント ページへのリンク
  • 最新のドキュメントコメントをリアルタイムに反映

ドキュメントのエクスポートと共有

（20:03）

ビルドが完了したら、ドキュメント パッケージ (.doccarchive) をエクスポートできます。

  1. ドキュメントナビゲータでフレームを右クリックします。 2.「エクスポート」を選択します。
  2. .docarchive ファイルとして保存します

他のユーザーは、ソース コードをダウンロードしたりビルドしたりせずに、.doccarchive をダブルクリックして Xcode でドキュメントを表示できます。

（20:36）

キーポイント:

  • .doccarchive にはコンパイルされたドキュメントが含まれています
  • アプリのようにダブルクリックで開くことができます
  • チームメンバーやユーザーとの共有に適しています
  • 静的 Web サイトとして展開することもできます

重要なポイント

  1. 初日から書く///ドキュメントのコメント。コードの横に書かれているので、コードが更新されたときに簡単に更新でき、コストはほぼゼロです。入口API：///注記。

  2. パブリック API の 使用例を提供します。 DocC は、コード ブロック内の型名をクリック可能なリンクに自動的に変換します。エントリ API: マークダウン コード ブロック。

  3. シンボリック リンクを使用して関連 API に接続します。ユーザーが API 間の関係を理解できるようにします。エントリ API: `SymbolName`。

  4. ドキュメント パッケージをエクスポートしてチームと共有します。ドキュメントを表示するために誰もがソース コードをビルドする必要はありません。入口 API: Documentation Navigator → エクスポート。

  5. DocC を CI プロセスに統合します。使用xcodebuild docbuildドキュメントを自動的に作成して検証します。入口API：xcodebuild docbuild -scheme MyFramework。

関連セッション

コメント

GitHub Issues · utterances