appledoc
appledoc是一个基于Objective-C的文档生成器，用它可以很方便的写出类似Apple官方风格的文档。
appledoc is command line tool that helps Objective-C developers generate Apple-like source code documentation from specially formatted source code comments.
Installation
从GitHub上把工程clone下来，再通过shell命令安装。
git clone git://github.com/tomaz/appledoc.git
cd appledoc
sudo sh install-appledoc.shDocumenting
Objective-C documentation is designated by a /** */ comment block (note the extra initial star), which precedes any @interface or @protocol, as well as any method or @property declarations.
以下面这段代码来说明：
/** Returns the absolute path of the Homebrew executable.
*
* @return The Homebrew executable path.
*/
- (NSString *)brewPath;
/** Sets the absolute path of the Homebrew executable.
*
* @param path The absolute path of the Homebrew executable. If `nil` the
* default path `/usr/local/bin/brew` will be used.
*/
- (void)setBrewPath:(NSString *)path;
/**-----------------------------------------------------------------------------
* @name Performing an Operation
* -----------------------------------------------------------------------------
*/
/** Performs an operation.
*
* Operations are placed in a queue for execution and will always execute on
* separate threads. Use setConcurrentOperations: to control how queued
* operations are executed (i.e. concurrently, or serially).
*
* @param operation The operation to perform.
* @param delegate The delegate object for the operation. The delegate will
* receive delegate messages during execution of the operation when output is
* generated and upon completion or failure of the operation.
*/
- (void)performOperation:(MRBrewOperation *)operation delegate:(id<MRBrewDelegate>)delegate;description
在**后面写description，更详细的discussion另起一行后再写。
/** description
*
* discussion
*
*/@name
相当于#pragma mark的功能，给代码分段。
/**-----------------------------------------------------------------------------
* @name Part 1
* -----------------------------------------------------------------------------
*/@param
@param [param] [Description]: 对参数的描述。
* @param url The URL to access.@return
@return [Description]: 对返回值的描述。
* @return The return value of the method.@see
@see [selector]: 提供see also的指引，引出相关的内容。
* @see +manager@warning
@warning [description]: 提供警示内容。
* @warning Call out exceptional or potentially dangerous behavior这些是一些常用的标识，更多的Javadoc-style @ labels看这里。
VVDocumenter-Xcode
onevcat开源的VVDocumenter-Xcode插件，安装之后重启Xcode，再输入 /// 就能自动生成一个文档注释的模板，很方便。
Usage
按照规范写好后，按住option键点击方法名，就能看到类似Apple文档的说明了。
如果想生成.docset文件，便于导入Dash之类的软件，只需要输入如下命令即可：
appledoc -p testappledoc -c Jo2Studio --company-id com.jo2studio -o ./doc .会将当前文件夹下的所有源文件进行扫描，生成文档，并在当前目录下的doc/文件夹下，新建一个文本文件，记录生成情况。
生成的文档文件默认会存放到：
~/Library/Developer/Shared/Documentation/DocSets
更多可用的参数可以用appledoc --help查看。或者查看官方的wiki。
p.s. 生成.docset文件后，在Xcode使用时，显示的内容反而不如之前多了。建议生成文档文件后将其移出默认系统文件夹。