Xcode文档注释使用总结

Xcode作为iOS的开发神器，为我们提供了十分丰富的文档提示功能，在开发过程中，我们可以十分方便的按下Option键，选中一个类或者方法查看其文档说明。而实际开发过程中我们也可以使用规范的方法添加注释，达到这样的效果。本篇主要介绍几种常用的文档注释方法。

一、多行注释文档

/**
    多行注释文档相比于普通多行注释多了一个星号。
    在这里可以使用markDown语法，书写各种提示信息
    如：显示一个有序列表
    1. 有序列表
    2. 有序列表
    3. 有序列表
*/

多行注释文档效果图

我们发现一个问题，效果图中前两行并没有换行，我们若是希望换行就需要在之间添加一个空行

---

二、单行注释文档

 ///# 标题1
 ///## 标题2
 ///hello oc，下面的空行是为了换行
 ///
 ///hello swift
 /// - 这里使用了无序列表
 /// - 使用加粗 **this**， 使用斜体 _this_
 /// - 添加一个链接: [百度](http://www.baidu.com)
 /// - 添加一个图片:![swift picture](http://img0.imgtn.bdimg.com/it/u=14209024,814391630&fm=21&gp=0.jpg )

单行注释文档效果图

---

三、方法/函数的注释

方法的注释包括传入参数、返回值、和异常等说明

///- 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效果图