iOS 注释规范及appledoc文档导出记录

快速注释

• 属性注释

/** <#注释*> */ 

• 单行注释

// ----<#单行注释#>----

• 方法注释
  Xcode 8后Command + Option + /快捷键可以给方法快速添加注释
• 方法集注释

查看时带分割线
#pragma mark  -  ====<#注释的内容#>====  
查看时带分割线
 #pragma mark  ====<#注释的内容#>====  

以上注释都可以通过自定义代码片段，以快捷键的方式快速创建。

appledoc文档导出

• 安装

打开终端，通过输入以下命令进行安装
$ git clone git://github.com/tomaz/appledoc.git
$ cd ./appledoc
$ sudo sh install-appledoc.sh

• 查看是否安装成功

查看版本号
$ appledoc --version
查看更多文档信息
$ appledoc --help

• 使用
  1、在终端中进入要导出文档的目录下

$ cd [文件夹]   注：此文件夹可以是项目的所在，也可以是项目中你要导出文档的文件夹，例：Views、Controlls、Models或者是他们的集合，所以项目文件分层很重要

2、输入如下命令：

默认生成的是Docset文档
$ appledoc --project-name "项目名称" --project-company "公司名称"./ 

3、添加更多参数，可通过命令：

查看更多文档信息
$ appledoc --help  如：生成html格式的文档，就需要添加`--no-create-docset`参数。命令为：$ appledoc --no-create-docset --project-name "项目名称" --project-company "公司名称" ./

⚠️注意：

1、./导出到当前路径的一个参数，前面要有空格！
2、如果你使用了第三方或安装了CocoaPods依赖管理工具，可能会报错。不过你可以cd到项目的子文件夹，导出你想导出的文件。

写在最后

记录一些关于 appledoc支持的注释规范、语法、MarkDown等

/// 这是单行注释。

/** 这也是单行注释 */

/*! 同样是单行注释 */

/** 这也是单行注释，
*  第二行会接上第一行。
*/

/** 
 @brief 这里是方法的简介。该Tag不能放到类注释里。
 @exception UIColorException 这里是方法抛出异常的说明
 @see 用它来指明其他相关的 method 或 function。你可以使用多个这种标签。
 @warning 这里是警告，会显示成蓝色的框框
 @bug 这里是bug，会显示成黄色的框框
 @param  这里是参数说明1
 @discusstion: 用它来写一段详尽的描述。如果需要你可以添加换行。
 @return  这里是返回值说明
 */

/** 第一行是类的简介
 
 在简介的下面,就是类的详细介绍了。
 没有间隔换行会被消除，就像Html那样。
 
 下面是常用的markdown语法

 分割线：

 - - -
 
 无序列表: (每行以 '*'、'-'、'+' 开头):

 * this is the first line
 * this is the second line
 * this is the third line
 
 有序列表: (每行以 1.2.3、a.b.c 开头):

 a. this is the first line
 b. this is the secode line
 
 多级列表:

 * this is the first line
    a. this is line a
    b. this is line b
 * this is the second line
    1. this in line 1
    2. this is line 2
 
 标题:

 # This is an H1
 ## This is an H2
 ### This is an H3
 #### This is an h4
 ##### This is an h5
 ###### This is an H6
 
 链接:

 普通URL直接写上，appledoc会自动翻译成链接: http://blog.ibireme.com
 [这个](http://example.net/) 链接会隐藏实际URL.
 
 表格:

 | header1 | header2 | header3 |
 |---------|:-------:|--------:|
 | normal  |  center |  right  |
 | cell    | cell    | cell    |
 
 */

感谢:
ibireme Blog

---

欢迎指正！