福利整理-如何在XCode 6中利用注释生成文档

原创Blog，转载请注明出处

http://blog.csdn.net/hello_hwc

由于最近公司的SDK要提交第一个版本，所以在忙着写文档，找了一些资料，自己也实际应用了一些，把一些经验写出来，分享给需要的人。

本博文主要针对XCode 6 和Objective C语言
后续会更新Swift语言如何生成文档

我的两个有关swift的专栏

http://blog.csdn.net/column/details/swfitexperience.html

http://blog.csdn.net/column/details/swift-hwc.html

一、关于可生成文档的注释
几个常用的标签

@brief   	简短的描述属性、类、协议、方法
@discussion 	和brief类似
@param   	描述属性
@return  	描述返回值
@warning 	警告信息(生成单独的warning描述)
@see		生成see also描述

注释的格式

/*!
 * 内容
 */

1、注释一个属性

/*!
 * @discussion The ViewController class' car object.
 */
@property (nonatomic) Car *car;

按control + 鼠标左键会出现如下图

NOTE:如果没出现不要着急，因为会有延迟

然后光标放到这个变量中间，会出现下图

2、注释一个方法

/*!
 * @discussion A really simple way to calculate the sum of two numbers.
 * @param firstNumber An NSInteger to be used in the summation of two numbers
 * @param secondNumber The second half of the equation. 
 * @return The sum of the two numbers passed in.
 */
+ (NSInteger)addNumber:(NSInteger)firstNumber toNumber:(NSInteger)secondNumber;

然后option + 鼠标左键
会出现如下图




3、注释一个类或者代理

/*!
 * @brief Class descripthion
 * @author hello_hwc from CSDN
 * @version 1.0 
 */

4、注释枚举

typedef enum {
    /// A cool, old car.
    OldCarTypeModelT,
    /// A sophisticated older car.
    OldCarTypeModelA
} OldCarType;

二、生成文档

headerdoc2html -o ~/Desktop/documentation DocumentationExamples/
cd ~/Desktop/documentation
gatherheaderdoc .

headerdoc2html读DocumentationExample目录下的所有文件，然后寻找header2doc格式的注释，然后生成对应的文档

gatherheaderdoc .是对当前目录下生成的html进行归总

分别如下图

单个文档

汇总文档

三、生成快捷block自动填充，方便以后注释使用
在Xcode中拷贝如下代码

/*!
 * @discussion <#description#>
 * @param <#param description#>
 * @return <#return description#>
 */

注意<#description#>会变成自动填充：就是用tab可以切换的填充
然后会变成如下图


然后拖动可以tab切换的部分，如description，拉到右边的block部分生成自定义快捷填充


然后在对话框里填写
这里侧重填充completion shortcut：比如可以填充doccomment
这样下次你敲docco就会出现自动补全，让你去选

完成编辑后，在把block拉到最后，会看到你刚创建的快捷block，标注为user

建议对注释类、属性、方法分别创建不同的block，这样比较方便

在这里拉到最后

Note：
1、如何换行，不要使用\n，这样是不会换行的，要想换行，要保证两行之间相隔一行，这一行没有空格没有除星号外的字符
例如

/*!
 * first line
 *
 * second line
 */

2、有些注释好用的方式，在生成文档的时候不一定好用

四、注释可用的标签

一二三部分是亲测可生成文档的注释

对于其他只需要在XCode中使用的注释，给出一个例子和一幅图，看看就明白了

备注：由于版本更新，并不是所有的都可用，但是大部分都可用，不方便重写截图了，就直接给出原例子

@a Italic text @em with @@a or @@em.

 @b Bold text with @@b.

 @p Typewritter font @c with @@p or @@c.

 Backslashes and must be escaped: C:\\foo.

 And so do @@ signs: user@@example.com

 Some more text.
 @brief brief text
 @attention attention text
 @author author text
 @bug bug text
 @copyright copyright text
 @date date text
 @invariant invariant text
 @note note text
 @post post text
 @pre pre text
 @remarks remarks text
 @sa sa text
 @see see text
 @since since text
 @todo todo text
 @version version text
 @warning warning text

 @result result text
 @return return text
 @returns returns text


 @code
// code text
while (someCondition) {
    NSLog(@"Hello");
    doSomething();
}@endcode
 Last line text.

 @param param param text
 @tparam tparam tparam text
 */
- (void)myMethod {}

对应的注释图片

主要参考两个链接

http://www.raywenderlich.com/66395

http://stackoverflow.com/questions/19168423/what-are-the-new-documentation-commands-available-in-xcode-5