文章标题

本文转载于：http://www.jianshu.com/p/77e654b215ac
前言
在开发中编写文档注释是一个很好的习惯 , 但是有些Coder会觉得写一大片的注释过于繁琐和浪费时间 , 所以也就懒得去写 , 为了制止无注释的坏现象 , 下面我为大家讲解几种快速生成注释的好方法 . (我似乎又维护了开发界的和平)

方法
VVDocumenter插件
VVDocumenter-Xcode是Xcode上一款快速添加标准注释 , 并可以自动生成文档的插件 . 有了VVDocumenter-Xcode , 规范化的注释 , 只需要输入三个斜线“///”就可以搞定 , 非常方面实用.

下面我来讲解一下如何在Xcode7上使用.

首先从GitHub上下载VVDocumenter-Xcode 然后打开运行 , Xcode6的话可以无视下面的三步操作.

第一步:获取xcode的UUID

方法1：在终端上输入命令:

defaults read /Applications/Xcode.app/Contents/Info DVTPlugInCompatibilityUUID
执行后就可以得到:

获取Xcode UUID

方法二：在/Applications目录中找到Xcode.app，右键”显示包内容”，进入Contents文件夹，双击Info.plist打开，找到DVTPlugInCompatibilityUUID，拷贝后面的字符串

第二步 添加Xcode的uuid到VVDocumenter-Xcode的Info.plist文件

打开xcode插件所在的路径:

~/Library/Application Support/Developer/Shared/Xcode/Plug-ins
(打开路径的快捷键为 shift＋command＋g 然后输入上面的地址）

选择已经安装的插件例如VVDocumenter-Xcode , 右键”显示包内容”.

找到 info.plist 文件 , 找到DVTPlugInCompatibilityUUIDs的项目 , 添加一个Item , Value的值为之前Xcode的UUID , 保存.

info.plist
第三步 重启Xcode

Xcode 6之后 , 重启Xcode时会提示 “Load Bundle” 、 “Skip Bundle” , 这里必须选择”Load Bundle” , 不然插件无法使用.

选择Load Bundle
做到这一步 就已经完成了VVDocumenter的配置 , 接下来你就可以在任何想要加注释的地方输入 “///” 了.

PS: 如果你选择了 “Skip Bundles” , 那么你就算重新安装也不会看到了 . 这是因为 Xcode里面的黑名单机制 . 别急 , 有解决办法 , 看下面:
打开终端输入以下命令:

defaults delete com.apple.dt.Xcode DVTPlugInManagerNonApplePlugIns-Xcode-7.2
注意: 命令里的Xcode-7.2是你当前的Xcode版本号 , 务必填正确 . (此条命令结束 , 终端没有反应 , 即没有提示错误 , 就是正确的)

接下来再重启Xcode , 这次看到上面的提示再选择 “Load Bundles” 就OK啦~

自定义注释
如果你对注释的格式等等有很高的要求 , 需要按照自定义的格式去添加 , 那么下面我教大家一种很实用的技巧.

首先我们在Xcode中编写好我们需要的注释格式 , 这里我简单举个例子:

/*!
* @brief <#简要描述#>
*
* @param <#参数#>
*
* @return <#返回值#>
*/
其中 <# 内容 #> 这个标签在Xcode编码区域会自动转成可以实用 Tab 键切换的标签 , 我们有时在调用某个方法时 参数部分那个效果的就是这个 .

自定义格式注释
接下来我们将这段注释选中 :

选中注释
将Xcode 右下角的窗口打开

直接将选中的这段注释拖入右下角的窗口中:

拖入窗口
这是我们会看到这样的界面 , 其中Title 代表新添加的这个代码段的标题 , Summary 为这个代码段的简介描述 , Platform为这个代码段应用的平台 ,
Completion Shortcut 这个代表使用的快捷方式 , Completion Scopes 这个代表使用的范围.

设置代码段
这里我按照我的需求设置好了 , 下面我们演示一下使用效果 , 当我在代码编写窗口中 打出我们之前设置好的快捷方式关键字 , 代码自动填充提示框就会提示出刚才我添加的代码段标题 , 这是直接点击回车键 , 刚刚那一段注释就自动为我们添加好了.

代码自动填充提示框

怎么样 ? 是不是很方便 . 这种方法需要我们事先按照自己的需求配置好后才能使用 , 不过自由度相比插件而已要高很多 , 不光是注释 , 比如我们平时开发时 使用频率较高 格式变化不大的代码段都可以使用这个方法去实现 , 这里不再一一介绍了 , 如果你感兴趣的话 可以自己慢慢去发掘.

修改Xcode默认注释
当你创建一个新的.h .m文件时 , 你可以看到文件顶部Xcode为我们自动添加好了一些描述的注释 , 但这些注释仅仅是用来描述这个文件 , 无法满足我们生成文档时的一些需求 , 下面我来为大家讲解如何将Xcode默认注释修改成我们需要的格式.

首先右键 Xcode -> 选项 -> 在Finder中打开 -> 右键 -> 显示包内容Contents -> Developer -> Platforms -> iPhoneOS.platform -> Developer -> Library -> Xcode -> Templates -> File Templates

File Templates目录
仔细看看这些文件夹名称 , 有木有很熟悉的感觉 ? ? 没错 就是这个:

新文件
选中Source -> Cocoa Touch Class.xctemplate

这个目录下面有很多后缀名为Objective-C跟Swift的文件夹 , 这么多怎么看呢 ? 我们先打开NSObjectObjective-C下面的FILEBASENAME

NSObjectObjective-C

FILEBASENAME.h
上面那绿油油的注释就是我们要修改的东西了 , 注意它的格式 , 跟我们创建文件的头部注释是一样的.

这里用到了几个系统的预处理宏定义 .
包括: FILENAME、PROJECTNAME、FULLUSERNAME、DATE和COPYRIGHT , 分别表示的是文件名、项目名称、系统用户全称、当前日期和版权声明 , 这些宏定义可以用在我们修改之后的注释中 . 我把它修改成下面这样:

修改后的FILEBASENAME.h
这样就符合我们需要的文档注释的格式了 , 这里有一点要说一下 , 在你修改内容的时候可能会这样提示你:

权限不足
这个提示的意思是说你没有足够的权限去修改 , 这时候你可以通过终端去修改文件的权限 , 当然还有一种更方便的方法 , 你右键要修改的文件 , 将它拷贝到随便一个地方(我拷贝到了桌面) , 然后打开拷贝的这个文件 , 你会发现可以随意修改了 , 这时你修改好后 直接将这个文件拖到原文件所在的文件夹中 , 替换原文件 (此时可能需要你输入一下密码).

退出Xcode重新运行 , 然后创建一个新的类 , 我们就会发现新的类文件格式:

修改后的新类文件
这样我们需要的头文件注释文档已经自动生成了 , 而且是一次操作 , 永久受益 . 大家可以依照我演示的这个示例去修改其他的类文件 , 在@interface的注释模板上加上规范类信息的注释文档 , 就可以直接创建类的注释文档 . 是不是很实用 ?

总结
善于利用各种小工具 小技巧来为我们解决繁琐而重复的工作 , 可以让我们更加专注于开发 , 不但节约了时间 , 还规范了不容易注意的细节