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

Meet DocC documentation in Xcode

DocCDocumentationXcodeSwift
观看原视频

Highlight

Xcode 13 集成 DocC 文档编译器，支持从 Swift 代码注释自动生成 API 参考文档，支持文章（Articles）和教程（Tutorials），可导出为文档包分享，并计划开源。

核心内容

你维护了一个 Swift 框架，但文档一直是个痛点。用 Jazzy 生成的文档样式和 Apple 官方不一致，第三方依赖的文档分散在各处。团队成员和外部用户经常问你 “这个 API 怎么用”。

Xcode 13 的 DocC 解决了这个问题。它原生集成在 Xcode 中，使用和 Apple 开发者文档完全相同的渲染引擎。

详细内容

三种文档类型

（01:29）

DocC 支持三种文档类型：

  1. Reference：API 参考文档，从代码注释自动生成
  2. Articles：概念性文章，解释框架的整体设计和使用方式
  3. Tutorials：逐步教程，手把手教用户构建一个项目

构建文档

（04:36）

Xcode 13 提供三种构建文档的方式：

  1. Build Documentation 菜单：手动构建并查看
  2. Build Settings：每次编译时自动构建文档
  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）

关键点：

  • /// 标记文档注释（两个斜杠是普通注释）
  • 第一行是摘要，显示在列表和搜索结果中
  • 空行后是详细描述
  • Markdown 代码块会被渲染为语法高亮

符号链接

（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-click 代码中的符号，可以查看 Quick Help：

  • 显示符号的摘要和描述
  • 包含参数和返回值说明
  • 符号链接可点击跳转
  • 底部有 “Open in Developer Documentation” 链接

（13:22）

关键点：

  • Option-click 触发 Quick Help
  • 在源码编辑器和调用处都可用
  • 链接跳转到完整文档页面
  • 实时反映最新的文档注释

导出和分享文档

（20:03）

构建完成后，可以导出文档包（.doccarchive）：

  1. 在 Documentation Navigator 中右键点击框架
  2. 选择 Export
  3. 保存为 .doccarchive 文件

其他人双击 .doccarchive 即可在 Xcode 中查看文档，不需要下载或构建源代码。

（20:36）

关键点：

  • .doccarchive 包含编译后的文档
  • 可以像打开 app 一样双击打开
  • 适合分享给团队成员或用户
  • 也可以部署为静态网站

核心启发

  1. 从第一天开始写 /// 文档注释。写在代码旁边，更新代码时顺手更新，成本几乎为零。入口 API：/// 注释。

  2. 为公开 API 提供使用示例。DocC 会自动把代码块中的类型名转为可点击链接。入口 API：Markdown 代码块。

  3. 用符号链接连接相关 API。帮助用户理解 API 之间的关系。入口 API：`SymbolName`。

  4. 导出文档包分享给团队。不需要每个人都构建源代码就能查看文档。入口 API：Documentation Navigator → Export。

  5. 把 DocC 集成到 CI 流程。用 xcodebuild docbuild 自动构建和验证文档。入口 API：xcodebuild docbuild -scheme MyFramework。

关联 Session

评论

GitHub Issues · utterances