如何在Xcode中为Swift函数的参数标签而非参数名编写文档？

嘿，这个问题我之前也纠结过！确实Swift的官方文档工具在处理参数标签的文档上有点不直观，但其实是有办法的——毕竟参数标签是函数调用时的关键入口，这部分的文档优先级很高，我们可以通过注释明确关联标签和参数的关系。

常见场景的文档写法 #

1. 外部标签+内部参数名的情况

比如你有一个带明确外部标签的函数，像func calculateTotal(for items: [Int], with taxRate: Double)，可以直接把标签和参数名绑定说明，或者在描述里标注标签用途：

/// 计算商品总价（包含税费）
/// - Parameters:
///   - for items: 商品价格列表（调用时使用标签`for`传入）
///   - with taxRate: 税率（比如0.08代表8%，调用时使用标签`with`传入）
func calculateTotal(for items: [Int], with taxRate: Double) -> Double {
    let subtotal = items.reduce(0, +)
    return subtotal * (1 + taxRate)
}

不管是Xcode的代码提示，还是生成的DocC文档，调用者都能清晰知道该用什么标签触发函数调用。

2. 无外部标签/仅部分有标签的情况

如果函数是func logEvent(_ eventName: String, at timestamp: Date)这种，第一个参数无外部标签，第二个有at标签，文档里可以明确区分：

/// 记录事件日志
/// - Parameters:
///   - eventName: 事件名称（调用时无需标签，直接传入值即可）
///   - at timestamp: 事件发生的时间（调用时使用标签`at`传入）
func logEvent(_ eventName: String, at timestamp: Date) {
    print("\(timestamp): \(eventName)")
}

3. 简化版标签说明

要是觉得上面的写法有点繁琐，也可以直接在参数描述里点明标签：

/// 发送网络请求
/// - Parameter url: 请求目标地址（调用时使用标签`to`）
/// - Parameter method: 请求方法（调用时使用标签`using`）
func sendRequest(to url: String, using method: HTTPMethod) async throws -> Data {
    // 实现逻辑
}

关于Apple文档的补充 #

你说在Apple文档里没找到相关方法，其实是因为Swift的文档系统默认会在函数签名里展示参数标签，但没有专门把“如何为标签写文档”单独拎出来讲。不过通过上面的注释方式，完全可以把标签的使用说明整合到参数文档里，让调用者一目了然。

另外，如果你用Xcode生成DocC文档，最终的文档页面会同时显示函数的完整签名（包含所有标签）和你写的参数说明，两者结合起来就足够清晰了。

内容的提问来源于stack exchange，提问作者Jean-Baptiste Yunès