Apple 又開源一 Swift 項目，相當實用

作者丨Franklin Schrans

來源丨小集（ID：zsxjtip）

在 WWDC21 上，Apple 發(fā)布了 Swift-DocC，這是一種用于 Swift 框架和包的新文檔編譯器。Swift-DocC 提供了一種輕松的方式來編寫出色的文檔以及您的代碼，并為 Swift 代碼庫生成全面的文檔網站。它支持編寫為代碼注釋的 API 文檔、用 Markdown 編寫的長篇概念文章，甚至帶有集成圖像的分步教程。

Swift-DocC 包含在 Xcode 13 工具中，它有以下幾個開發(fā)目標：

• 與現(xiàn)有的開發(fā)工具集成。Swift-DocC 工具旨在無縫集成到現(xiàn)有的開發(fā)人員工作流程中，并直接在流行的編碼工具和 IDE 中工作。使用 Swift-DocC 創(chuàng)作文檔將很容易適應開發(fā)人員已經使用的相同版本控制過程。

• 簡化創(chuàng)作豐富的參考文檔。參考文檔是描述 API 行為的重要資源，也是第三方開發(fā)人員的最佳實踐。通常，API 之間的鏈接對于解釋它們的使用至關重要，因此使這些鏈接易于創(chuàng)作和驗證是一個關鍵目標。

• 鼓勵高水平的技術文章。從歷史上看，開發(fā)人員將高級說明文檔與 API 文檔分開編寫和維護，這使得這些內容最初不太可能被編寫，并且可能會過時。通過提供用于在代碼旁邊創(chuàng)作這些高級內容的工具，以及 API 和概念文檔的輕松互連，我們的目標是查看更多包含在包和框架中的概念文檔。

• 為新用戶添加豐富的教程。教程可以通過輕松創(chuàng)建友好的學習體驗來幫助提升第三方包的 Swift 生態(tài)系統(tǒng)，這對于不熟悉 API 的開發(fā)人員來說尤其有用。像文章一樣，教程可以很容易地包含在主要的文檔工作流程中

• 輕松將文檔連接在一起。組織良好的文檔會更容易找到。另一個關鍵目標是為開發(fā)人員提供一種直觀的方式來將文檔組織成邏輯組并編寫指向其他頁面的鏈接。

概述

Swift-DocC 包含幫助開發(fā)人員在許多平臺（包括 macOS 和 Linux）上編寫和生成文檔的工具和庫，其目標是通過 Swift 工具鏈支持所有平臺。docc 命令行工具已經集成在 Xcode 13 中，其架構方式可以與其他構建系統(tǒng)（如 SwiftPM）集成。開源項目由幾個組件組成，其中一些組件本身可能對構建其他開發(fā)人員工具很有趣。組件包括：

• Swift-DocC — 處理源文件注釋、獨立 Markdown 文件和相關資產以生成機器可讀 JSON 存檔的文檔編譯器工具。

• Swift-DocC-Render — 一種基于 JavaScript 的 Web 應用程序，可呈現(xiàn)已編譯的 DocC 檔案。

• Swift-Markdown — 一個可以在 Swift 中輕松解析 Markdown 語法的庫。

• SymbolKit — 一個 Swift 庫，用于解析 Swift 編譯器發(fā)出的符號圖文件。這些文件封裝了有關模塊 API 的信息，包括它們的文檔注釋。

該工具可以理解 Swift 社區(qū)中已經在 Jazzy 和 SwiftDoc 等杰出工具以及 Xcode 等 IDE 中流行的 Swift 文檔注釋語法。它還添加了一些新穎的語法功能。例如，雙反引SymbolName語法在符號之間創(chuàng)建鏈接。一個例子：

源文件文檔注釋

/// 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 開發(fā)人員可以從項目一開始就輕松地記錄他們的代碼。

與核心 Swift 工具的其他組件一樣，該項目將遵循 Swift Evolution 流程，首要任務之一是使用可擴展插件設計與 Swift Package Manager 的集成。很快，Swift 開發(fā)主干快照（適用于 Swift 5.5 之后的版本）將包含 Swift-DocC 工具。

采用

正在 swift.org/documentation 上托管為 Swift-DocC 項目本身生成的文檔。長期目標包括向更多包添加文檔，以及跨 Swift.org 遷移標準庫和其他文檔的文檔。這將使社區(qū)更容易參與 Swift 的記錄和教學。

-End-

最近有一些小伙伴，讓我?guī)兔φ乙恍?nbsp;面試題 資料，于是我翻遍了收藏的 5T 資料后，匯總整理出來，可以說是程序員面試必備！所有資料都整理到網盤了，歡迎下載！