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"
    }

---

源信息注释

这里是提供代码的作者，版权相关说明

    ///- 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:  一些评论心得