iOS代码注释文档生成

一、代码注释

参考https://useyourloaf.com/blog/swift-documentation-quick-guide/

Symbol Documentation
There are four sections, of which, only the description is always included:

• Description
• Parameters
• Throws
• Returns

Description：注释描述的写法

/**
 What does this function do? （这个部分就会自动生成Description的部分）
*/

func someFunction(name: String) -> Bool {
  return false
}

Parameters: 参数的写法

/**
 Another useful function
 - parameters:
   - alpha: Describe the alpha param
   - beta: Describe the beta param
*/
func doSomething(alpha: String, beta: String) {

}

或者

/**
 Another useful function
 - parameter alpha: Describe the alpha param
 - parameter beta: Describe the beta param
*/
func doSomething(alpha: String, beta: String) {}

Throws：抛异常的写法，只能出现一次

/// Some introductory test that describes the purpose
/// of the function.
/// - Throws: SomeError you might want to catch

func someFunction() throws -> Bool {

Returns：返回值的注释写法值能出现一次

/// Some introductory test that describes the purpose
/// of the function.
/// - Returns: true or false

func someFunction() throws -> Bool {}

如果需要一些高级的注释这里有一些关键字可供选择

关键字列表

- Attention: Watch out for this!
- Author: Tim Cook
- Authors:
  John Doe
  Mary Jones
- Bug: This may not work
- Complexity: O(log n) probably
- Copyright: 2016 Acme
- Date: Jan 1, 2016
- experiment: give it a try
- important: know this
- invariant: something
- Note: Blah blah blah
- Precondition: alpha should not be nil
- Postcondition: happy
- Remark: something else
- Requires: iOS 9
- seealso: something else
- Since: iOS 9
- Todo: make it faster
- Version: 1.0.0
- Warning: Don't do it

例如：

/**
     Another useful function  
     - Warning: ddddd （在生成的注释文档中会有一红色的备注框）
    */
    func doSomething(alpha: String, beta: String) {
        
    }

二、生成代码注释文档

苹果支持markdown的注释文档，生成步骤：

• cmd+n 选择documentation下的 documentation Catalog
• 然后 Product–>build documentation 或者 快捷键：shift+control+cmd+d
  这样就会生成注释文档，文档可以导出。