关于查看自已写的方法的“描述”(AppleDoc)

呵呵，才疏学浅，不知道怎么描述了，以至于标题都写的这么有诗意，看下图吧。

如上图，一般来说，系统给的方法，当按着“Option”键+鼠标点击的时候会弹出上图，上面有描述啥的。而我们自已写的方法，却只有一句：

今天闲来无事儿，研究了一这个东东，发现原来我们自已写的方法也可以实现最上面那张图的效果的。原来这个东东叫作“文档”或者说是“帮助文档”，其实就是代码注释和说明，按照一定的格式写，然后通过一个叫作AppleDoc的神器转换一下，就可以实现基本和系统文档差不多的效果，过程如下：
1.安装AppleDoc

git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.sh

会不会觉得上面的方法麻烦？我也是这么认为的，所以我最先用了下面的方法:

brew install appledoc

省事倒是省事儿，很快就完事儿了，结果就是：一直有错误，不好使。最好还是乖乖的用了上面的方法，手动编译的
2.使用AppleDoc

/usr/local/bin/appledoc \
--project-name umiwi \
--project-company rainbird \
--company-id com.umiwi.video.iphone \
--output ~/help \
.

就这么一句话，别告诉我你不知道这是要在terminal里输的。
网上的教程基本上都是告诉你，第一步，第二步，然后就完事了，包括官方文档也是这么干的。
但是咱没写过文档啊，虽然有代码注释的习惯，但是上面的指令运行了以后发现没啥效果。肿么个回事儿呢。
一方面：命令执行完，其实没有实时的生效。我用的是xcode4.5.2，看好多资料说4.x以后，上面的指令执行以后，是实时生效的，实际上在我的4.5.2是不好使的，即使用了4.x以前用的那个AppleScript也不好使，所以这里的忠告是:执行完上面的命令记得重启一下xcode
另一方面：就是文档的书写格式的问题了嘛，试了半天，用下面的代码实现了下下面的效果:

/**
 检查网络，有网络的话自动启动下载任务
 @param  无 不需要参数
 @return 没有返回值
 */
-(void)autoStartDownloadManager{
}

当然了，我上面只是举例，像我这个函数，没参数，没返回值，没必要写@param和@return的。再有就是注意空格:/** 内容 */。如果写一行就要注意“内容”的前后都要有空格。如果像我上面写多行/**后面可以不用有空格，后面的东东前面都要有空格的哟。还有一个不爽的地方就是不管你@前面的内容是写一行，还是写几行，显示出来的时候都是连在一块儿的，囧一个~
再有就是上面的那条命令嘛时候执行的问题，我们知道运行工程的时候，可以在工程编译完执行一下脚本，但是每次编译程序都要执行一下这条脚本是不是很浪费时间呢？如果觉得是的话，可以单建一个叫作“Aggregate”的Target，然后把脚本写上，需要生成文档的时候，执行一下。
再费话一句：我觉得这个生成文档的方式很鸡肋呢。因为通过option+左键点击查看定义有直接command+左键点击过去查看快么？后者虽然麻烦一点儿，但是不用想着再生成一遍文档啊。咋想都是个挺麻烦的事儿。

转载请注明: 转自Rainbird的个人博客