Swift Digest
この記事の要点
- Swift のフレームワークやパッケージ向けのドキュメントコンパイラ Swift-DocC がオープンソース化され、macOS や Linux を含む複数のプラットフォームでサポートされました。WWDC21 で発表され Xcode 13 に同梱されていたツールが、誰でも利用・貢献できる形で公開されたものです。
- Swift-DocC は、コードコメントとして書く API ドキュメント、Markdown で書く長文の解説記事、画像を組み込んだ step-by-step のチュートリアルをまとめて扱い、Swift コードベースから包括的なドキュメントサイトを生成します。
- プロジェクトはドキュメントコンパイラ本体に加え、
doccアーカイブを描画する Web アプリ、Markdown パーサ、シンボルグラフのパーサといった複数のコンポーネントで構成され、それぞれ独立して他の開発ツールにも活用できます。
何が発表されたのか
Swift-DocC は、WWDC21 で Apple が発表した Swift フレームワーク・パッケージ向けの新しいドキュメントコンパイラです。コードのそばで質の高いドキュメントを手軽に書き、Swift コードベースから包括的なドキュメントサイトを生成できます。Xcode 13 のツールに同梱されていましたが、今回これがオープンソース化され、複数プラットフォームのサポートとともに公開されました。
Swift-DocC は次のような目標のもとで開発されました。
- 既存の開発ツールとの統合。 普段のコーディングツールや IDE の中で直接動き、既存の開発ワークフローやバージョン管理のプロセスにそのまま組み込めること。
- リッチなリファレンスドキュメントの作成を容易にすること。 API 同士のリンクは使い方を説明するうえで重要なため、リンクを簡単に書け、検証もできるようにすること。
- 高レベルの技術記事を書きやすくすること。 従来は API ドキュメントと別に管理されがちで古くなりやすかった概念的な解説を、コードのすぐそばに書けるようにすること。
- 新規利用者向けのチュートリアルを追加できること。 API に不慣れな開発者にも親しみやすい学習体験を、メインのドキュメントワークフローの中で用意できること。
- ドキュメント同士を結びつけやすくすること。 ドキュメントを論理的なグループに整理し、ほかのページへのリンクを直感的に書けるようにすること。
何ができるのか
Swift-DocC は macOS や Linux を含む多くのプラットフォームでドキュメントを書き、生成するためのツールとライブラリで構成されます。docc コマンドラインツールは Xcode 13 に統合済みで、SwiftPM など他のビルドシステムとも連携できる設計になっています。オープンソースプロジェクトは次のコンポーネントから成り、いくつかは他の開発ツールを作るうえでもそれ自体が有用です。
- Swift-DocC — ソースコメント・単独の Markdown ファイル・関連アセットを処理し、機械可読な JSON アーカイブを生成するドキュメントコンパイラ。
- Swift-DocC-Render — コンパイル済みの DocC アーカイブを描画する JavaScript ベースの Web アプリケーション。
- Swift-Markdown — Swift で Markdown 構文を簡単にパースできるライブラリ。
- SymbolKit — Swift コンパイラが出力するシンボルグラフファイルをパースする Swift ライブラリ。モジュールの API とそのドキュメントコメントの情報を含みます。
Swift-DocC は、Jazzy や SwiftDoc、そして Xcode などですでに広く使われている Swift のドキュメントコメント構文を理解します。そのうえで独自の構文も追加しています。たとえばダブルバッククォート ``SymbolName`` でシンボル間のリンクを作れます。
/// A model representing a sloth.
///
/// You can create a sloth using the ``init(name:color:power:)`` initializer, or
/// create a randomly generated sloth using a ``SlothGenerator``:
///
/// ```swift
/// let slothGenerator = MySlothGenerator(seed: randomSeed())
/// let habitat = Habitat(isHumid: false, isWarm: true)
/// do {
/// let sloth = try slothGenerator.generateSloth(in: habitat)
/// } catch {
/// fatalError(String(describing: error))
/// }
/// ```
public struct Sloth { … }
このようなコメントが、相互リンクの張られたドキュメントサイトのページとして描画されます。
導入・今後の位置づけ
Swift-DocC は GitHub で試せます。Swift-DocC 自体のドキュメント（Swift-DocC で書かれています）は swift.org/documentation で公開されており、利用方法の相談は Using Swift forum、実装・開発の議論は Swift-DocC forum で行えます。
発表時点で示されていた今後の構想であり、実現を約束するものではありません。
- Swift ツールへの統合。 ドキュメントのビルドをコードのビルドと同じくらい簡単にするため、Swift-DocC をコアの Swift ツールに同梱することが次の段階として挙げられていました。このプロジェクトは Swift Evolution プロセスに従って進められ、最初の作業のひとつとして、拡張可能なプラグインを使った Swift Package Manager との統合の設計が予定されていました。Swift 5.5 より後のリリースに向けた開発トランクのスナップショットに Swift-DocC ツールが含まれる見込みも示されていました。
- 採用の拡大。 まず Swift-DocC プロジェクト自体のドキュメントが swift.org/documentation でホストされました。より長期的には、より多くのパッケージへのドキュメント追加や、標準ライブラリ・Swift.org 全体のドキュメント移行が目標として掲げられていました。