Swift 文档编写指南：如何清晰高效地撰写文档

轻松学习Python，无需理论负担。在浏览器中直接解决带自动检查的实践任务，无需安装任何东西。

引言：为什么 Swift 项目的文档是必需品

在 iOS 和 macOS 开发领域，高质量的文档往往是将业余项目与专业产品区分开来的关键因素。许多 Swift 开发者忽视代码文档，依赖"自文档化"的语法。然而，当项目扩展到数万行代码，团队中又有新成员加入时，缺乏清晰的文档就会变成严重问题。

Apple 积极推广文档文化：从 Xcode 13 开始，DocC（Documentation Compiler）工具已成为事实标准。它允许直接从源代码创建丰富、交互式的文档。在本文中，我们将探讨如何为 Swift 项目正确编写文档——从简单的注释到完整的参考指南。

文档基础：从注释到 DocC

Swift 中的文档格式

Swift 支持两种主要的注释格式：单行注释（//）和多行注释（/* */）。文档使用扩展的 Markdown 语法，以 ///（单行）或 /** */（多行）开头。

函数文档的基本示例：

/// 计算数字的阶乘。
///
/// 此函数使用递归方法计算阶乘。
/// - Parameter n: 非负整数。
/// - Returns: 数字 n 的阶乘。
/// - Warning: 此函数不处理负数。
func factorial(_ n: Int) -> Int {
    guard n >= 0 else { return 0 }
    return n == 0 ? 1 : n * factorial(n - 1)
}

文档的关键元素

编写 Swift 文档时，请使用以下关键词（参数）：

- Parameter — 函数参数的描述
- Returns — 返回值的描述
- Throws — 可能错误的描述
- Warning — 重要警告
- Note — 附加说明
- Precondition — 调用的前置条件
- Complexity — 算法复杂度评估

DocC：创建专业文档

什么是 DocC？

DocC（Documentation Compiler）是 Apple 的一个工具，它将 Swift 源代码中的文档编译成静态 HTML 网站。它支持：

自动生成所有 public 和 open 类型的文档
连接文章、指南和 API 参考
嵌入图片、图表和代码示例
交互元素：指向文档其他部分的链接

在项目中配置 DocC

要启用 DocC，只需在项目中添加 Documentation.docc 文件夹。内部创建扩展名为 .md 的文件。基本结构：

MyProject/
├── Sources/
│   └── MyProject/
│       └── MyClass.swift
└── Documentation.docc/
    ├── MyProject.md
    └── Articles/
        └── GettingStarted.md

SwiftUI 类的文档示例

/// 用于显示用户个人资料的视图。
///
/// 使用此组件显示头像、姓名和简要信息。
/// ```swift
/// UserProfileView(userName: "安娜", avatar: "person.circle.fill")
/// ```
public struct UserProfileView: View {
    let userName: String
    let avatar: String
    
    public var body: some View {
        HStack {
            Image(systemName: avatar)
                .resizable()
                .frame(width: 50, height: 50)
            Text(userName)
                .font(.title2)
        }
    }
}