Create rich documentation with Swift-DocC
Swift & UI 进阶 20m

使用 Swift-DocC 创建丰富的文档

Create rich documentation with Swift-DocC

2023年6月5日

在 Apple 官方观看视频

一句话判断

Xcode 15 为 Swift-DocC 带来了实时预览编辑器——边写文档边看渲染效果，还新增了代码片段、教程文章、自定义主题等能力，写文档终于不再是”写完再构建验证”的痛苦流程。

这场 Session 讲了什么

Session 介绍了 Xcode 15 中 Swift-DocC 的全面升级。

Documentation Preview 编辑器。这是最亮眼的更新。在源码编辑器中编写文档注释时，通过 Editor > Assistant > Documentation Preview 打开实时预览。每输入一个字符，预览都会即时更新。你可以看到文档最终渲染的完整效果——标题、代码块、参数说明、返回值描述，全部实时呈现。

代码片段。DocC 现在支持在文档中嵌入可运行的代码片段。不只是静态的代码展示，你可以标注代码的哪些部分是关键步骤，配合教程引导读者逐步理解。

教程（Tutorials）。DocC 新增了对分步教程的支持——一种介于 API 参考和博客文章之间的文档形式。教程由多个步骤组成，每个步骤包含介绍、代码和预览。

跨平台支持。Swift-DocC 现在支持文档化 App 和 Framework，不管使用 Swift、Objective-C 还是两者混合。开源的 Swift-DocC 项目在社区推动下增加了这些能力。

发布方式。文档兼容静态网站托管（GitHub Pages、Netlify 等），也会出现在 Xcode 的内置文档窗口和 Quick Help 中。

值得深挖的点

实时预览改变了写文档的节奏：以前写文档是”写一批 -> 构建 -> 检查 -> 修改”的循环。现在变成了实时反馈，就像在 Markdown 编辑器里写文章一样自然。这大幅降低了写文档的心理阻力。

教程的定位：API 参考文档告诉开发者每个参数是什么，但不会告诉他们”怎么用”。教程填补了这个空白——通过分步骤的引导，开发者可以在文档中直接学习框架的使用方式。这对降低 SDK 的学习曲线很有价值。

代码片段的双重身份：在 API 参考中，代码片段是”使用示例”；在教程中，代码片段是”操作步骤”。DocC 用统一的语法支持了这两种场景。

代码片段

编写带有实时预览的 Swift-DocC 文档：

/// 一个用于追踪鸟类观测的模型。
///
/// 使用 ``BirdTracker`` 来记录你在野外观察到的鸟类。
/// 每条记录包含物种、观测时间和地点。
///
/// ## 快速开始
///
/// ```swift
/// let tracker = BirdTracker()
/// tracker.record(species: .blueJay, location: .applePark)
/// let recentSightings = tracker.recentSightings(count: 10)
/// ```
///
/// - Important: 使用前需要在 Info.plist 中请求位置权限。
///
/// - Note: 观测数据通过 iCloud 在设备间同步。
public class BirdTracker {
    /// 记录一次鸟类观测。
    ///
    /// - Parameters:
    ///   - species: 观测到的鸟类物种
    ///   - location: 观测地点
    /// - Returns: 创建的观测记录，如果参数无效则返回 nil
    public func record(species: BirdSpecies,
                       location: Location) -> Sighting? {
        // 实现细节...
    }
}

最佳实践

  • 利用 Documentation Preview 边写边看，确保文档排版符合预期
  • 为公开 API 编写 DocC 注释，Xcode Quick Help 会自动展示
  • 代码片段要可运行——读者会复制粘贴到项目中
  • 教程适合引导开发者完成一个完整的”从零到一”流程
  • 文档中的图片放在 Documentation Catalog 中管理

还有什么值得关注

  • Swift-DocC 的自定义主题和品牌化能力
  • 教程的完整语法和分步结构
  • Objective-C 代码的文档化方式
  • 静态托管和版本化文档的最佳实践
WWDC 2023