Apple 又開源一 Swift 項(xiàng)目，相當(dāng)實(shí)用
在 WWDC21 上，Apple 發(fā)布了 Swift-DocC，這是一種用于 Swift 框架和包的新文檔編譯器。Swift-DocC 提供了一種輕松的方式來編寫出色的文檔以及您的代碼，并為 Swift 代碼庫生成全面的文檔網(wǎng)站。它支持編寫為代碼注釋的 API 文檔、用 Markdown 編寫的長(zhǎng)篇概念文章，甚至帶有集成圖像的分步教程。
Swift-DocC 包含在 Xcode 13 工具中，它有以下幾個(gè)開發(fā)目標(biāo)：
與現(xiàn)有的開發(fā)工具集成。Swift-DocC 工具旨在無縫集成到現(xiàn)有的開發(fā)人員工作流程中，并直接在流行的編碼工具和 IDE 中工作。使用 Swift-DocC 創(chuàng)作文檔將很容易適應(yīng)開發(fā)人員已經(jīng)使用的相同版本控制過程。
簡(jiǎn)化創(chuàng)作豐富的參考文檔。參考文檔是描述 API 行為的重要資源，也是第三方開發(fā)人員的最佳實(shí)踐。通常，API 之間的鏈接對(duì)于解釋它們的使用至關(guān)重要，因此使這些鏈接易于創(chuàng)作和驗(yàn)證是一個(gè)關(guān)鍵目標(biāo)。
鼓勵(lì)高水平的技術(shù)文章。從歷史上看，開發(fā)人員將高級(jí)說明文檔與 API 文檔分開編寫和維護(hù)，這使得這些內(nèi)容最初不太可能被編寫，并且可能會(huì)過時(shí)。通過提供用于在代碼旁邊創(chuàng)作這些高級(jí)內(nèi)容的工具，以及 API 和概念文檔的輕松互連，我們的目標(biāo)是查看更多包含在包和框架中的概念文檔。
為新用戶添加豐富的教程。教程可以通過輕松創(chuàng)建友好的學(xué)習(xí)體驗(yàn)來幫助提升第三方包的 Swift 生態(tài)系統(tǒng)，這對(duì)于不熟悉 API 的開發(fā)人員來說尤其有用。像文章一樣，教程可以很容易地包含在主要的文檔工作流程中
輕松將文檔連接在一起。組織良好的文檔會(huì)更容易找到。另一個(gè)關(guān)鍵目標(biāo)是為開發(fā)人員提供一種直觀的方式來將文檔組織成邏輯組并編寫指向其他頁面的鏈接。
概述
Swift-DocC 包含幫助開發(fā)人員在許多平臺(tái)（包括 macOS 和 Linux）上編寫和生成文檔的工具和庫，其目標(biāo)是通過 Swift 工具鏈支持所有平臺(tái)。docc?命令行工具已經(jīng)集成在 Xcode 13 中，其架構(gòu)方式可以與其他構(gòu)建系統(tǒng)（如 SwiftPM）集成。開源項(xiàng)目由幾個(gè)組件組成，其中一些組件本身可能對(duì)構(gòu)建其他開發(fā)人員工具很有趣。組件包括：
Swift-DocC?— 處理源文件注釋、獨(dú)立 Markdown 文件和相關(guān)資產(chǎn)以生成機(jī)器可讀 JSON 存檔的文檔編譯器工具。
Swift-DocC-Render?— 一種基于 JavaScript 的 Web 應(yīng)用程序，可呈現(xiàn)已編譯的 DocC 檔案。
Swift-Markdown?— 一個(gè)可以在 Swift 中輕松解析 Markdown 語法的庫。
SymbolKit?— 一個(gè) Swift 庫，用于解析 Swift 編譯器發(fā)出的符號(hào)圖文件。這些文件封裝了有關(guān)模塊 API 的信息，包括它們的文檔注釋。
該工具可以理解 Swift 社區(qū)中已經(jīng)在 Jazzy?和?SwiftDoc?等杰出工具以及 Xcode 等 IDE 中流行的 Swift 文檔注釋語法。它還添加了一些新穎的語法功能。例如，雙反引SymbolName語法在符號(hào)之間創(chuàng)建鏈接。一個(gè)例子：
源文件文檔注釋
/// 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 { … }
渲染的結(jié)果
下一步
與 Swift 工具集成
構(gòu)建文檔應(yīng)該像構(gòu)建代碼一樣簡(jiǎn)單。為此，接下來的步驟將包括將 Swift-DocC 與核心 Swift 工具一起使用，以便所有 Swift 開發(fā)人員可以從項(xiàng)目一開始就輕松地記錄他們的代碼。
與核心 Swift 工具的其他組件一樣，該項(xiàng)目將遵循 Swift Evolution 流程，首要任務(wù)之一是使用可擴(kuò)展插件設(shè)計(jì)與 Swift Package Manager 的集成。很快，Swift 開發(fā)主干快照（適用于 Swift 5.5 之后的版本）將包含 Swift-DocC 工具。
采用
正在?swift.org/documentation?上托管為 Swift-DocC 項(xiàng)目本身生成的文檔。長(zhǎng)期目標(biāo)包括向更多包添加文檔，以及跨 Swift.org 遷移標(biāo)準(zhǔn)庫和其他文檔的文檔。這將使社區(qū)更容易參與 Swift 的記錄和教學(xué)。