WWDC Quick Look 💓 By SwiftGGTeam
中文 EN 日本語
What's new in Swift-DocC

What's new in Swift-DocC

Developer ToolsDocumentationSwift
元の動画を見る

ハイライト

Xcode 14 の Swift-DocC は、アプリ プロジェクトのドキュメントの作成をサポートし、Objective-C/C API をサポートします。DocC アーカイブは GitHub Pages などの静的ホスティング サービスに直接公開でき、新しい Web ナビゲーション サイドバーも追加されています。

主要内容

その文書はどこに書かれており、誰に見せるべきですか?

Swift-DocC は昨年 Xcode 13 で導入されましたが、サポートされるのは Swift フレームワークのみです。多くの開発者は、アプリ プロジェクトの内部ドキュメントを作成したり、Objective-C プロジェクトのドキュメントを作成したりしたいと考えていますが、それは機能しません。

Xcode 14 は、Swift-DocC を 4 つの新しいシナリオに拡張します。

  1. アプリ プロジェクトのドキュメント: チーム メンバーが共同作業するときは、プロジェクトの構造と API の使用法を理解する必要があります。
  2. Objective-C および C API ドキュメント: 混合言語プロジェクトはドキュメント ツールを統合できます
  3. ワンクリックで Web サイトに公開: DocC Archive は静的ホスティングと直接互換性があります。
  4. Web ナビゲーション サイドバー: ドキュメントの閲覧エクスペリエンスが大幅に向上しました。

ソースコードのコメントから完全なドキュメントサイトまで

Swift-DocC のコンテンツは、単一 API のリファレンス ドキュメント、概念的な記事、ステップバイステップのチュートリアルの 3 つの層に分かれています。 Xcode 14 では、3 つのレベルすべてのコンテンツをソース コードとドキュメント カタログから生成できます。

詳細

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

（03:18）

/// A view that displays a sloth.
///
/// This is the main view of ``SlothyApp``.
/// Create a sloth view by providing a binding to a sloth.
///
///

```swift
/// @State private var sloth: Sloth
///
/// var body: some View {
///     SlothView(sloth: $sloth)
/// }
///

struct SlothView: View 


**キーポイント:**
- 使用`///`DocC は 3 つのスラッシュで始まる場合のみ認識できます。
- 最初の段落は概要であり、ページ タイトルの下に表示されます。
- 後続の段落は概要領域に入ります
- `` `SlothyApp` `` 二重バッククォートで囲むと、DocC が自動的に API リンクに変換されます
- リンクは構築中に検証され、失敗した場合は警告が報告されます。
- サンプルコードを挿入するためのマークダウンコードブロック構文

### イニシャライザとメソッドのパラメータに関するドキュメントを作成する

（[04:25](https://developer.apple.com/videos/play/wwdc2022/110368/?time=265)）

```swift
struct SlothView: View {
    /// Creates a view that displays the specified sloth.
    ///
    /// - Parameter sloth: The sloth the user will edit.
    init(sloth: Binding<Sloth>) {
        // ...
    }
}

キーポイント:

  • - Parameter各パラメータを説明するリスト
  • パラメータの説明は別のパラメータ領域に表示されます。
  • 複数のパラメータの場合- Parameters:パック

Objective-C API ドキュメント

（05:24）

/// A sound that can be played.
///
/// Use an instance of this type to play a sound
/// to the user in response to an action or
/// event.
@interface SLOSound : NSObject

/// Creates a sound given its name and path on
/// disk.
///
/// - Parameters:
///   - name: The name of the sound.
///   - filePath: The path to the sound file on disk.
- (id)initWithName:(NSString *)name
          filePath:(NSString *)filePath;

@end

キーポイント:

  • Xcode 14 は、Objective-C および C の DocC ドキュメントのサポートを開始します
  • 構文は Swift と同じです。///とマークダウン
  • バイリンガル API ページには、現在使用している言語に応じて表示される言語切り替えボタンがあります。

ドキュメントカタログとトップレベルページ

（06:48）

プロジェクトのソース コード フォルダーを右クリックし、[新しいファイル] → [ドキュメント カタログ] を選択します。 Xcode は、トップレベルのページ ファイルを含むドキュメント ディレクトリを自動的に作成します。

# ``Slothy``

An app to create and care for custom sloths.

## Overview

Slothy is an iOS app that allows users to create and care for virtual sloths.

![An illustration displaying the UI for finding, creating, and taking care of a sloth in Slothy.](slothy.png)

The Slothy app project contains views to present Slothy's user interface, and utilities to play sounds as the user interacts with the app.

キーポイント:

  • ドキュメント カタログはソース コード ドキュメントを補足し、概念的な記事やメディア ファイルを保存します
  • トップレベルページの場合# ``ModuleName`` 構文ステートメント
  • 埋め込み画像などのリッチメディアをサポート
  • これは、寄稿者がドキュメントを開いたときに最初に表示されるページです

GitHub ページに公開する

（08:03）

DocC Archive 自体は完全な静的 Web サイトです。 Xcode 14 によって生成されたアーカイブは、ほとんどの Web サーバーおよびホスティング サービスと直接互換性があります。

GitHub ページの URL には特定のベース パス (username.github.io/repo-name)、DocC に次のように伝える必要があります。

// Build Settings 中设置
DocC Archive Hosting Base Path = sloth-creator

次に、ドキュメントをビルドし、ドキュメント ウィンドウからアーカイブをエクスポートし、コンテンツをウェアハウスの docs ディレクトリにコピーして、プッシュ用に送信します。

キーポイント:

  • 独自のドメイン名にアーカイブされたコンテンツを Web サーバーのルート ディレクトリに直接コピーします
  • GitHub Pages等ではHosting Base Pathの設定が必要
  • DocC アーカイブは静的ファイルであり、あらゆる静的ホスティング サービスでサポートされています

Swift Package Managerプラグインの自動化

（14:03）

Swift-DocC は、ドキュメント構築プロセスを自動化するための Swift Package Manager プラグインを提供します。 GitHub Actions などの CI ツールを使用すると、ドキュメントは更新されるたびに自動的に再構築され、GitHub Pages にデプロイされます。

コマンドラインでのビルド方法:

# Xcode 项目
xcodebuild docbuild -scheme MyScheme

# Swift Package（使用 DocC 插件）
swift package --allow-writing-to-directory ./docs \
    generate-documentation --target MyTarget \
    --output-path ./docs

Web ナビゲーション サイドバー

（14:46）

Xcode 14 の DocC Web ページには、新しい左側のナビゲーション バーがあります。

  • 開閉用三角ボタンをクリックして、タイプ階層を展開または折りたたむことができます。
  • ページを開かずにサブページの一覧を確認できます
  • 下部のフィルター バーは、キーワードによるシンボルのフィルター処理をサポートします。
  • ページ間を移動するときにサイドバーのステータスが維持されるため、閲覧パスを追跡しやすくなります

重要ポイント

  • DocC ドキュメントをチーム プロジェクトに追加 一般にリリースされていないアプリの場合でも、内部ドキュメントは新しいメンバーがすぐに使い始めるのに役立ちます。から///コメントから始めて、各パブリック API の概要とパラメーターの説明を書きます。

  • フレームワークのドキュメントを GitHub ページに公開 オープンソースの Swift パッケージとオンライン ドキュメントを組み合わせることで、ユーザー エクスペリエンスが大幅に向上します。ホスティング ベース パスを設定し、GitHub アクションを使用して自動的にデプロイし、リリースされるたびにドキュメントを同期的に更新します。

  • Objective-C レガシー コードのドキュメント 統合ツールを使用して、混合言語プロジェクトを文書化できるようになりました。コアの Objective-C クラスに追加///コメントは、チームメンバーが Xcode で直接表示できます。

  • ドキュメント カタログを使用してプロジェクト ガイドラインを作成します API リファレンスだけでなく、カタログ内の Markdown ファイルを使用して、アーキテクチャの説明、開発仕様、アクセス ガイドを記述します。これらのコンテンツはコードとともにバージョン管理され、古くなることはありません。

  • ドキュメントのビルド チェックを CI に統合 バンドルxcodebuild docbuildまたはswift package generate-documentationCI プロセスに参加します。 DocC リンク検証は、API 名が変更された後にドキュメント内の無効なリンクを見つけるのに役立ちます。

関連セッション

コメント

GitHub Issues · utterances