What's new in Swift-DocC
System & Services 进阶 20m

Swift-DocC 的新功能

What's new in Swift-DocC

2022年6月6日

在 Apple 官方观看视频

一句话判断

Swift-DocC 今年补齐了最关键的几块拼图：支持应用项目文档、Objective-C 文档、以及一键发布到 GitHub Pages——现在没有理由不给项目写文档了。

这场 Session 讲了什么

Swift-DocC 团队的 Franklin 和 Ethan 介绍了 Xcode 14 中 Swift-DocC 的重要更新。去年发布的 Swift-DocC 已经支持 Swift 框架的文档编写，今年扩展到四个新领域：应用项目文档、Objective-C/C API 文档、简化的 Web 发布流程、以及全新的导航侧边栏。

Session 用一个叫 Slothy 的示例项目贯穿始终，演示了如何从零开始为包含 Swift 和 Objective-C 源文件的应用编写文档，并发布到网站。

Swift-DocC 现在是一个开源项目，新功能是在与开源社区的紧密协作中开发的。

值得深挖的点

应用项目文档支持。 这是今年最大的变化。以前 Swift-DocC 只能文档化框架，现在任何 Xcode 应用项目都可以直接生成文档。即使项目还没写任何文档注释，选择 Product > Build Documentation 就能看到自动生成的 API 存根页面，为后续填充提供起点。

Objective-C 文档支持。 使用与 Swift 相同的 Markdown 语法，你可以为 Objective-C 代码编写文档注释。对于同时支持 Swift 和 Objective-C 调用的 API，DocC 自动显示语言切换开关，用户可以选择查看对应语言的版本。

静态托管变得极其简单。 Xcode 14 生成的 DocC Archive 直接兼容大多数 Web 服务器。对于 GitHub Pages，大多数情况下只需将 Archive 复制到 gh-pages 分支即可。不再需要额外的构建步骤或服务器端处理。

全新的导航侧边栏。 文档网站现在有了一个结构化的侧边栏导航，按模块和类型层级组织内容。这让开发者更容易发现和浏览你的文档。

代码片段

/// 用于展示树懒信息的视图。
///
/// 使用 ``SlothView`` 来在应用界面中展示树懒的详细信息。
/// 你可以通过传入 ``Sloth`` 对象来初始化这个视图。
///
/// ```swift
/// let sloth = Sloth(name: "小懒", habitat: .rainforest)
/// let slothView = SlothView(sloth: sloth)
/// ```
struct SlothView: View {
    /// 要展示的树懒对象。
    let sloth: Sloth
    
    /// 创建一个新的树懒视图。
    /// - Parameter sloth: 需要展示的树懒。
    init(sloth: Sloth) {
        self.sloth = sloth
    }
}
/**
 * @brief 表示一种声音效果的类。
 *
 * @discussion SLOSound 用于播放与树懒活动相关的音效。
 * 支持同时播放多个声音实例。
 */
@interface SLOSound : NSObject

/**
 * @brief 创建一个新的声音实例。
 * @param name 声音的标识符。
 * @return 初始化后的声音对象。
 */
- (instancetype)initWithName:(NSString *)name;

@end

最佳实践

  • 从 /// 三斜杠注释开始，为每个公开 API 编写简洁的摘要
  • 为初始化器和方法逐个描述参数，使用 - Parameter 语法
  • 使用 DocC 的链接语法（双反引号）引用其他 API，链接在构建时会被验证
  • 添加代码示例帮助其他开发者快速上手
  • 使用 Documentation Catalog 创建项目顶级页面，提供整体介绍
  • 为文档页面嵌入图片等富媒体内容增强可读性
  • 利用 DocC Archive 的静态托管能力，将文档发布到 GitHub Pages

还有什么值得关注

  • Swift-DocC 是开源项目，可以在 swift.org 上参与贡献
  • 文档链接在构建时会被验证，如果引用的 API 不存在会产生警告
  • Documentation Catalog 可以包含教程（Tutorials），适合编写分步指南
  • 对于框架项目，文档发布后可以帮助其他开发者发现和使用你的 API
WWDC 2022