DocC生成SwiftUI文档时参数显示异常、返回值缺失求助

参数显示异常的原因 #

你的DocC注释中- Parameters :的冒号后多了空格，正确语法应为- Parameters:（冒号后直接换行，不要加空格），格式错误导致DocC无法正确解析参数列表，才出现只显示一个‘s’的异常。

返回值缺失的原因 #

函数返回的是匿名元组，但注释仅描述了第一个元素，且Returns的格式不符合DocC要求。同时原函数返回的元组未命名，DocC无法自动关联注释内容，需要调整注释写法或给元组元素命名。

修正后的代码 #

/// meanRounds 计算回合的平均值
///
/// （目前暂不可用，正在开发mean2版本）
///
/// - Parameters:
///   - values: 存储数值的数组
///   - times: 存储每个数值出现次数的数组
///   - min: 出现的最小值
///   - max: 出现的最大值
/// - Returns: 包含三个元素的元组：
///   - 计算得到的平均值
///   - 固定返回的2.0
///   - 固定返回的Double类型数组
func meanRounds(values:[Int], times: [Int], min: Int, max: Int) -> (Double,Double,[Double]) {
    
    var averageValue = mean2(values: values, times: values.count)
    
    return (averageValue,2.0,[1.0,2.0,3.0,4.0,5.0])
}

如果想让返回值的每个元素在DocC里有更清晰的命名展示，可以给返回元组命名后对应注释：

/// meanRounds 计算回合的平均值
///
/// （目前暂不可用，正在开发mean2版本）
///
/// - Parameters:
///   - values: 存储数值的数组
///   - times: 存储每个数值出现次数的数组
///   - min: 出现的最小值
///   - max: 出现的最大值
/// - Returns: 包含以下元素的元组：
///   - average: 计算得到的平均值
///   - fixedDouble: 固定返回的2.0
///   - fixedArray: 固定返回的Double类型数组
func meanRounds(values:[Int], times: [Int], min: Int, max: Int) -> (average: Double, fixedDouble: Double, fixedArray: [Double]) {
    
    var averageValue = mean2(values: values, times: values.count)
    
    return (averageValue,2.0,[1.0,2.0,3.0,4.0,5.0])
}

关键注意点 #

• DocC注释语法对格式要求严格，Parameters、Returns这类标记后不能加多余空格，必须是- Parameters:和- Returns:的标准格式。
• 对于元组返回值，要么清晰描述每个元素的含义，要么给元组元素命名，DocC才能正确生成对应的返回值文档。

内容的提问来源于stack exchange，提问作者Heki