通用格式

每一行文档注释前面使用 /// 符号。不使用 Javadoc 的风格（/** ... */）。Javadoc 的风格不适合复制粘贴。

  1. ✅
  2. /// Returns the numeric value of the given digit represented as a Unicode scalar.
  3. ///
  4. /// - Parameters:
  5. ///   - digit: The Unicode scalar whose numeric value should be returned.
  6. ///   - radix: The radix, between 2 and 36, used to compute the numeric value.
  7. /// - Returns: The numeric value of the scalar.
  8. func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  9.   // ...
  10. }
  1. ❌
  2. /**
  3.  * Returns the numeric value of the given digit represented as a Unicode scalar.
  4.  *
  5.  * - Parameters:
  6.  *   - digit: The Unicode scalar whose numeric value should be returned.
  7.  *   - radix: The radix, between 2 and 36, used to compute the numeric value.
  8.  * - Returns: The numeric value of the scalar.
  9.  */
  10. func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  11.   // ...
  12. }
  14. /**
  15. Returns the numeric value of the given digit represented as a Unicode scalar.
  17. - Parameters:
  18.   - digit: The Unicode scalar whose numeric value should be returned.
  19.   - radix: The radix, between 2 and 36, used to compute the numeric value.
  20. - Returns: The numeric value of the scalar.
  21. */
  22. func numericValue(of digit: UnicodeScalar, radix: Int = 10) -> Int {
  23.   // ...
  24. }

一句话总结

文档注释开始应该是一句简短的总结性介绍。如果还有一些细节信息需要补充，换行后重起一段话。这句概括的话不要求是一个完整的句子。比如一个方法的文档不用以“这个方法xxxx”开头。因为既然是这个方法的文档，那么通过上下文已经知道了这个信息，没必要在文档里带上“这个方法”，这是冗余的信息。不过这句话还是要以句号结尾。

  1. ✅
  2. /// The background color of the view.
  3. var backgroundColor: UIColor
  5. /// Returns the sum of the numbers in the given array.
  6. ///
  7. /// - Parameter numbers: The numbers to sum.
  8. /// - Returns: The sum of the numbers.
  9. func sum(_ numbers: [Int]) -> Int {
  10.   // ...
  11. }
  1. ❌
  2. /// This property is the background color of the view.
  3. var backgroundColor: UIColor
  5. /// This method returns the sum of the numbers in the given array.
  6. ///
  7. /// - Parameter numbers: The numbers to sum.
  8. /// - Returns: The sum of the numbers.
  9. func sum(_ numbers: [Int]) -> Int {
  10.   // ...
  11. }

Parameter, Returns, Throws 标签

如果文档要说明参数、返回值、抛出的错误，使用 Parameter（s）、Returns、Throws 标签。如果需要换行，在下一行前面缩进两个空格。强烈建议使用 Xcode 的快捷键 Command + Option + / 根据函数签名生成文档模板。如果函数的总结描述已经够清楚，参数和返回值可以不需要再做说明。每一行还是要以句号结尾。如果只有一个参数使用 Parameter，有一个以上参数使用 Parameters。下面是例子：

  1. ✅
  2. /// Returns the output generated by executing a command.
  3. ///
  4. /// - Parameter command: The command to execute in the shell environment.
  5. /// - Returns: A string containing the contents of the invoked process's
  6. ///   standard output.
  7. func execute(command: String) -> String {
  8.   // ...
  9. }
  11. /// Returns the output generated by executing a command with the given string
  12. /// used as standard input.
  13. ///
  14. /// - Parameters:
  15. ///   - command: The command to execute in the shell environment.
  16. ///   - stdin: The string to use as standard input.
  17. /// - Returns: A string containing the contents of the invoked process's
  18. ///   standard output.
  19. func execute(command: String, stdin: String) -> String {
  20.   // ...
  21. }

苹果的 Markup 格式

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

  • 段落之间使用以 /// 开头的单行分隔。

  • 一个星号包裹 表示斜体。

  • 两个星号包裹表示粗体。

  • \单引号里包裹``表示代码。

  • 里面可以包裹一整块代码。

文档注释 - 图1

什么时候写文档

至少每一个 open 或者 public 的声明都应该有文档注释。以下这些情况可以例外：

  • enum 的每一个选项有的时候本身命名已经很清晰了，可以不用写。如果是 associated value 要特别注意关联类型的含义是否足够清晰，否则还是应该写文档说明。

  • 如果是 override 了父类的方法、属性，或者实现了一个 protocol，或者用给 protocol 在 extension 中添加默认实现，可以不用写。如果 override 改变了原有的行为还是应该写文档说明的。如果行为没有变化重新声明一遍已有的文档则是多余的。

  • 测试用的类和方法视情况可以不写。

  • Extension 的文档注释有时可以省略。如果文档没有阐述 extension 的意图可以不写。

下面的例子的文档只是重复了已知的信息，没有意义：

  1. ❌
  2. /// Add `Equatable` conformance.
  3. extension MyType: Equatable {
  4.   // ...
  5. }

如果你的文档只是简单地重复源文件中显而易见的信息，这样的文档还是不要写了。