Xcode文档注释使用总结
2016-08-16 本文已影响587人
梧雨北辰
Xcode作为iOS的开发神器，为我们提供了十分丰富的文档提示功能，在开发过程中，我们可以十分方便的按下Option键，选中一个类或者方法查看其文档说明。而实际开发过程中我们也可以使用规范的方法添加注释，达到这样的效果。本篇主要介绍几种常用的文档注释方法。
一、多行注释文档
/**
多行注释文档相比于普通多行注释多了一个星号。
在这里可以使用markDown语法，书写各种提示信息
如：显示一个有序列表
1. 有序列表
2. 有序列表
3. 有序列表
*/
多行注释文档效果图
我们发现一个问题，效果图中前两行并没有换行，我们若是希望换行就需要在之间添加一个空行
二、单行注释文档
///# 标题1
///## 标题2
///hello oc，下面的空行是为了换行
///
///hello swift
/// - 这里使用了无序列表
/// - 使用加粗 **this**， 使用斜体 _this_
/// - 添加一个链接: [百度](http://www.baidu.com)
/// - 添加一个图片:
单行注释文档效果图
三、方法/函数的注释
方法的注释包括传入参数、返回值、和异常等说明
///- Parameters:
/// - value1: 第一个传入参数
/// - value2: 第二个传入参数
///- Returns: 返回值的说明
///- Throws : 出现异常的说明
func doSomeThing(value1:String, vaule2:String, value3:String)->String{
return "testStr"
}
方法/函数的注释效果图
四、源信息注释
这里是提供代码的作者，版权相关说明
///- Author: zs
///- Authors: 开发人员 zs, cf
///- CopyRight: 版权信息
///- Date: 15 July 当前开发时间
///- Since: iOS 8.0
///- Version: 2.26
五、标签注释
标签注释穿插在我们代码的任意位置，我们通过xcode的类视图来查找标签，可以快速定位，十分方便，常见的三种注释标签如下：
//MARK: - 在代码的某处添加一个标签，可以使查看类视图更加方便
//TODO: - 将来可能会继续编辑的部分
//FIXME: - 将要修改的部分
标签注释效果图
六、算法注释
算法是相对比较复杂的方法，我们通过注释对其进行详尽的说明，其文档注释使用的关键字如下：
/// - Precondition: 前置条件
/// - Postcondition: 后置条件
/// - Requires: 算法需要的信息
/// - Invariant: 循环不变量
/// - Complexity: 复杂度
/// - Important: 描述重要信息
/// - Warning: 描述警告信息
/// - Attention: 描述注意事项
/// - Note: 一些记录
/// - Remark: 一些评论心得
算法注释x效果图
