在WWDC21上，苹果宣布了Swift-DocC，一个用于Swift框架和包的新文档编译器。Swift-DocC提供了一种毫不费力的方式来编写与你的代码一起的伟大文档，并为Swift代码库生成全面的文档网站。它支持以代码注释形式编写的API文档、以Markdown编写的长篇概念性文章，甚至是带有集成图片的分步骤教程。
Swift-DocC包含在Xcode 13工具中，而人们已经在为他们的代码添加更多的文档。当它在WWDC21上宣布时，一些工程师提到Swift-DocC将作为开放源代码发布。而这一天现在已经到来，并支持多个平台。
Swift-DocC的开发目标如下：
- 与现有开发工具整合：Swift-DocC工具的建立是为了无缝集成到现有的开发者工作流程中，并直接在流行的编码工具和IDE中工作。使用 Swift-DocC 编写文档将很容易融入开发人员已经使用的相同版本控制流程。
- 简化丰富的参考文档的编写工作：参考文档是描述您的 API 行为的重要资源，也是第三方开发者的最佳实践。通常，API之间的链接对于解释它们的使用至关重要，所以使这些链接易于编写和验证是一个关键目标。
- 鼓励高水平的技术文章：从历史上看，开发者撰写和维护高水平的教育性文件与API文档是分开的，这使得这些内容首先不可能被撰写，而且可能会过时。通过在代码旁边提供编写这种高级内容的设施，以及API和概念性文档的简单相互联系，我们的目标是看到更多的概念性文档包含在软件包和框架中。
- 为新用户增加丰富的教程：教程可以帮助提升第三方软件包的Swift生态系统，使其易于创建友好的学习体验，这对刚接触API的开发者来说尤其重要。像文章一样，教程可以很容易地包含在主要的文档工作流程中
- 使得文档容易连接在一起：当文档被很好地组织起来时，就更容易找到它。另一个关键目标是为开发者提供一种直观的方式，将文档组织成逻辑组，并写上与其他页面的链接。
概述
Swift-DocC包含了帮助开发者在许多平台上编写和生成文档的工具和库，包括macOS和Linux，其目标是用Swift工具链支持所有平台。docc 命令行工具已经集成在Xcode 13中，其架构方式可以与其他构建系统（如SwiftPM）集成。这个开源项目由几个组件组成，其中一些组件本身可能对构建其他开发者工具很有意思。这些组件包括：
- Swift-DocC- 文档编译工具，用于处理源文件注释、独立的 Markdown 文件和相关资产，以生成机器可读的 JSON 档案。
- Swift-DocC-Render- 一个基于 JavaScript 的网络应用程序，用于显示编译后的 DocC 档案。
- Swift-Markdown- 一个可以在Swift中轻松解析Markdown语法的库。
- SymbolKit- 一个能解析由Swift编译器发出的符号图文件的Swift库。这些文件封装了关于模块的API的信息，包括它们的文档注释。
该工具能够理解Swift文档的注释语法，这种语法已经在Swift社区的杰出工具（如Jazzy和SwiftDoc）以及Xcode等IDE中流行。例如，双后缀``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 工具集成
构建文档应该像构建代码一样简单。为此，接下来的步骤之一是将 Swift-DocC 与核心 Swift 工具整合在一起，这样所有 Swift 开发人员就可以从项目一开始就轻松记录他们的代码。
与Swift核心工具的其他组件一样，这个项目将遵循Swift进化过程，首要任务之一是设计与Swift Package Manager的整合，使用可扩展插件。而且很快，Swift开发主干快照（用于Swift 5.5之后的版本）将包括Swift-DocC工具。
