原创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进行归总
分别如下图
单个文档
汇总文档
在Xcode中拷贝如下代码
/*!
* @discussion <#description#>
* @param <#param description#>
* @return <#return description#>
*/
注意<#description#>会变成自动填充:就是用tab可以切换的填充
然后会变成如下图
然后拖动可以tab切换的部分,如description,拉到右边的block部分生成自定义快捷填充
然后在对话框里填写
这里侧重填充completion shortcut:比如可以填充doccomment
这样下次你敲docco就会出现自动补全,让你去选
完成编辑后,在把block拉到最后,会看到你刚创建的快捷block,标注为user
建议对注释类、属性、方法分别创建不同的block,这样比较方便
在这里拉到最后
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