Meet DocC documentation in Xcode
Developer Tools 入门 22m

初识 Xcode 中的 DocC 文档系统

Meet DocC documentation in Xcode

2021年6月8日

在 Apple 官方观看视频

一句话判断

DocC 不只是”Xcode 自带的 Jazzy 替代品”——它是 Apple 把文档编写从”附属品”提升为”一等公民”的尝试，如果你维护一个 Swift 库，没有理由不用它。

这场 Session 讲了什么

Session 介绍了 Xcode 13 中全新集成的 DocC（Documentation Compiler）系统。DocC 是 Apple 开发的文档编译器，可以将代码中的 Markdown 格式注释编译成精美的网页文档，支持文章（Articles）、教程（Tutorials）和 API 参考三种内容类型。

过去 Swift 项目的文档方案主要依赖 Jazzy 等第三方工具，输出样式和 Apple 官方文档不一致。DocC 原生集成在 Xcode 中，使用和 Apple 开发者文档完全相同的渲染引擎。你在代码中写的 /// 注释会被 DocC 自动提取为 API 参考文档。额外的 Article 和 Tutorial 文件用 Markdown 编写，放在项目的 Documentation 目录下。编译后的文档可以直接在 Xcode 的 Documentation Window 中查看，也可以导出为静态网站部署到任何 Web 服务器。

值得深挖的点

DocC 的 Markdown 方言（Documentation Markup）

DocC 使用一种扩展的 Markdown 语法。除了标准的标题、列表、代码块之外，它支持几种特殊结构：@Code 引用代码片段、@Image 嵌入图片、@Row / @Column 布局排版、@TabNavigator 创建标签页切换。最有用的是 @Links 和 @Reference——可以创建类型之间的交叉引用。当你的文档提到另一个类型时，DocC 自动生成可点击的链接，不需要手写 URL。

Tutorial 的分步引导设计

DocC 的 Tutorial 功能可以创建交互式的分步教学文档。每个步骤包含一段说明文字、一段代码示例和一个 Checkpoint（检查点）。用户可以逐步跟进代码修改，Xcode 会在 Documentation Window 中高亮显示当前步骤的代码变化。这个功能非常适合编写框架的入门教程——比单独维护一个 GitHub Wiki 好太多。

代码片段

/// 一个用于管理用户会话的服务类。
///
/// `SessionManager` 负责处理用户的登录、登出和会话状态管理。
/// 它使用 ``TokenProvider`` 来获取和刷新访问令牌。
///
/// ## 使用示例
///
/// ```swift
/// let manager = SessionManager(tokenProvider: myProvider)
/// manager.login(username: "user", password: "pass")
/// ```
///
/// - Note: 此类不是线程安全的，请在主线程上使用。
///
/// - Important: 在 iOS 15 及以上版本中，`login` 方法是 async 的。
public class SessionManager {
    /// 当前的登录状态。
    ///
    /// 可能的值包括 ``SessionState/loggedIn``、``SessionState/loggedOut``
    /// 和 ``SessionState/expired``。
    public var state: SessionState
    
    /// 使用指定的 token 提供者初始化会话管理器。
    /// - Parameter tokenProvider: 用于获取访问令牌的提供者。
    public init(tokenProvider: TokenProvider) {
        self.tokenProvider = tokenProvider
        self.state = .loggedOut
    }
    
    /// 异步登录用户。
    /// - Parameters:
    ///   - username: 用户名
    ///   - password: 密码
    /// - Returns: 登录成功后的用户信息
    /// - Throws: ``SessionError`` 如果登录失败
    public func login(username: String, password: String) async throws -> User {
        // 实现省略
    }
}
<!-- Documentation/Article/GettingStarted.md -->
# 入门指南

欢迎使用 MyFramework！这个指南将帮助你快速上手。

## 概述

MyFramework 提供了网络请求、数据缓存和用户认证三大核心功能。

@TabNavigator {
    @Tab "SwiftUI" {
        ```swift
        import MyFramework
        
        struct ContentView: View {
            var body: some View {
                ProfileView()
                    .task {
                        await SessionManager.shared.login()
                    }
            }
        }
        ```
    }
    @Tab "UIKit" {
        ```swift
        import MyFramework
        
        class ViewController: UIViewController {
            override func viewDidLoad() {
                super.viewDidLoad()
                Task {
                    try? await SessionManager.shared.login()
                }
            }
        }
        ```
    }
}

## 下一步

了解更多关于 ``TokenProvider`` 的配置选项，请查看 <doc:ConfigurationGuide>。
// 在 Xcode build setting 中启用 DocC
// Build Settings > Build Options > Build Documentation During 'Build' = YES
// 或者在命令行中使用：
// xcodebuild docbuild -scheme MyFramework -destination generic/platform=iOS

// 导出编译后的文档为静态网站
// (Xcode > Product > Build Documentation)
// 输出目录: ~/Library/Developer/Xcode/DerivedData/.../Documentation/
// 可以直接部署到 GitHub Pages 或任意静态托管服务

最佳实践

  • 从第一天就开始写文档注释——不要等项目完成了再补。/// 注释写在代码旁边，更新代码时顺手更新文档，成本几乎为零。
  • 为公开 API 提供至少一个使用示例代码块。DocC 会把代码块中的类型名自动转换为可点击的链接，用户可以在文档中直接跳转。
  • Tutorial 文件用 @Steps 和 @Code 组织，保持每个步骤只讲一个概念。长篇大论的 Tutorial 比没有文档更糟糕。

还有什么值得关注

  • DocC 生成的文档可以在 Xcode 的 Documentation Window 中直接搜索，和 Apple 官方文档混合显示。
  • Apple 已经开源了 DocC 的编译器和渲染器，社区可以贡献主题和插件。
  • xcodebuild docbuild 命令支持在 CI 环境中自动编译文档，配合 GitHub Actions 自动部署。
WWDC 2021