通用格式

每一行文档注释前面使用 /// 符号。不使用 Javadoc 的风格(/** ... */)。Javadoc 的风格不适合复制粘贴。
✅
/// Returns the numeric value of the given digit represented as a Unicode scalar.
///
/// - Parameters:
///   - digit: The Unicode scalar whose numeric value should be returned.
///   - radix: The radix, between 2 and 36, used to compute the numeric value.
/// - Returns: The numeric value of the scalar.
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  // ...
}
❌
/**
 * Returns the numeric value of the given digit represented as a Unicode scalar.
 *
 * - Parameters:
 *   - digit: The Unicode scalar whose numeric value should be returned.
 *   - radix: The radix, between 2 and 36, used to compute the numeric value.
 * - Returns: The numeric value of the scalar.
 */
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  // ...
}
​
/**
Returns the numeric value of the given digit represented as a Unicode scalar.
​
- Parameters:
  - digit: The Unicode scalar whose numeric value should be returned.
  - radix: The radix, between 2 and 36, used to compute the numeric value.
- Returns: The numeric value of the scalar.
*/
func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  // ...
}

一句话总结

文档注释开始应该是一句简短的总结性介绍。如果还有一些细节信息需要补充,换行后重起一段话。这句概括的话不要求是一个完整的句子。比如一个方法的文档不用以“这个方法xxxx”开头。因为既然是这个方法的文档,那么通过上下文已经知道了这个信息,没必要在文档里带上“这个方法”,这是冗余的信息。不过这句话还是要以句号结尾。
✅
/// The background color of the view.
var backgroundColor: UIColor
​
/// Returns the sum of the numbers in the given array.
///
/// - Parameter numbers: The numbers to sum.
/// - Returns: The sum of the numbers.
func sum(_ numbers: [Int]) -> Int {
  // ...
}
❌
/// This property is the background color of the view.
var backgroundColor: UIColor
​
/// This method returns the sum of the numbers in the given array.
///
/// - Parameter numbers: The numbers to sum.
/// - Returns: The sum of the numbers.
func sum(_ numbers: [Int]) -> Int {
  // ...
}

Parameter, Returns, Throws 标签

如果文档要说明参数、返回值、抛出的错误,使用 Parameter(s)、Returns、Throws 标签。如果需要换行,在下一行前面缩进两个空格。强烈建议使用 Xcode 的快捷键 Command + Option + / 根据函数签名生成文档模板。如果函数的总结描述已经够清楚,参数和返回值可以不需要再做说明。每一行还是要以句号结尾。如果只有一个参数使用 Parameter,有一个以上参数使用 Parameters。下面是例子:
✅
/// Returns the output generated by executing a command.
///
/// - Parameter command: The command to execute in the shell environment.
/// - Returns: A string containing the contents of the invoked process's
///   standard output.
func execute(command: String) -> String {
  // ...
}
​
/// Returns the output generated by executing a command with the given string
/// used as standard input.
///
/// - Parameters:
///   - command: The command to execute in the shell environment.
///   - stdin: The string to use as standard input.
/// - Returns: A string containing the contents of the invoked process's
///   standard output.
func execute(command: String, stdin: String) -> String {
  // ...
}

苹果的 Markup 格式

写文档的时候可以灵活的使用苹果的 markup 格式。这些标记可以被 Xcode 识别,在阅读的时候可以被渲染出不同的格式。有一些和 markdown 格式很接近。列出几个常用的:

什么时候写文档

至少每一个 open 或者 public 的声明都应该有文档注释。以下这些情况可以例外:
下面的例子的文档只是重复了已知的信息,没有意义:
❌
/// Add `Equatable` conformance.
extension MyType: Equatable {
  // ...
}
如果你的文档只是简单地重复源文件中显而易见的信息,这样的文档还是不要写了。