swift添加注释

一，为何添加注释

1.方便查找，定位代码

2.方便新人快速上手

二，希望达到的效果

1.按住 Option/Alt 键点击属性名、方法名或类名等，会弹出快速预览（Quick Look preview）

2.光标移动到属性名、方法名或类名上，打开快速帮助（Quick Help Inspector）进行查看

三，工具可使用第三方工具产生使用手册

如oc中的 HeaderDoc and Doxygen

在swift中可使用Jazzy, 它是一个命令行工具

四，安装，使用Jazzy

1.sudo gem install jazzy注意：Jazzy 依赖于 Xcode command-line developer tools，如果 build 报错，可尝试 xcode-select —install若是提示ERROR: While executing gem ... ,改成sudo gem install -n /usr/local/bin jazzy即可

2.cd 到已添加注释工程目录

3.jazzy --min-acl internal, 其中internal进行文档化的访问权限，可改为fileprivate或private, 默认public和open或者 jazzy --swift-version x.x.x --min-acl internal x.x.x为xcode支持的swift版本,比如我的目前是4.1，最终是jazzy --swift-version 4.1 --min-acl internal

4.设置作者jazzy —author lcl4

5.docs/index.html 即是所需

五，注释

示例

1.类，属性

在上方添加 (/// 备注) 即可（注意空格）

例:

/// 数据帧封装类

public class MTLCLFrame: NSObject { 

 /// 当前帧时间 

 public var currentSampleTime : CMTime? 

 /// 方向 

 public var orientation : MTLCLImageOrientation?

 /// 数据帧 

 public var sampleBuffer : CMSampleBuffer? 

 /// 图像 

 public var image : CIImage? 

 /// 来源 

 public var sourceType : MTLCLSourceType?

 /// 参数字典 

 public var parameters : Dictionary = Dictionary()

}

2.枚举

在枚举上方添加 (/** 备注 */) 或者 (/// 备注) ，在case上添加(/// 备注)即可

例：

/**

数据帧来源枚举.

*/

public enum MTLCLSourceType {

    /// 视频来源

    case video

    /// 图像来源

    case photo

}

3.若是想让文档分段，并添加每段的标题，在适当位置添加 (// MARK: 备注)

例：

// MARK: 相机主要方法

4.方法

在方法上方添加 /** */，- parameter, - returns等关键字， /** */内关键字上方为方法描述

例:

    /**

    设置聚焦.

    - Parameter focusMode: 聚焦模式.

    - Parameter exposureMode: 曝光模式.

    - Parameter point: 焦点.

    - Precondition: 'point' should not be nil.

    - Requires: Both focusMode and exposureMode should support for current device.

    - Remark:

    此方法包括三个参数，没有返回。用于界面点击时设置相机相关参数.

    */

关键字说明：

Pameter为方法参数

Returns为方法返回

Remark粗体显示，需要读者注意的地方

Warning警告

Version版本

Author作者

Todo之后版本可能添加的Feature

Precondition和Requires希望使用方法的读者注意的地方

oc中生成文档(使用HeaderDoc)：

(inputPath : /Users/meitu/Desktop/DocDemo

outputPath : /Users/meitu/Desktop/Doc/HeaderDoc)

cd /Users/meitu/Desktop/DocDemo

headerdoc2html -o /Users/meitu/Desktop/Doc/HeaderDoc /Users/meitu/Desktop/DocDemo

headerdoc2html -o

cd /Users/meitu/Desktop/Doc/HeaderDoc

headerdoc2html -o /Users/meitu/Desktop/DocDemo/

gatherheaderdoc /Users/meitu/Desktop/Doc/HeaderDoc

oc中生成文档(Doxygen为第三方，需要下载和配置)

注意，oc的注释风格与swift不同