Objective-C规范注释心得——同时兼容appledoc（docset、html）与doxygen（html、pdf）的文档生成

作者：zyl910

　　手工写文档是一件苦差事，幸好现在有从源码中抽取注释生成文档的专用工具。对于Objective-C来说，目前最好用的工具是appledoc和doxygen。可是这两种工具对于注释的要求略有区别。于是我经过一番摸索，找到了一套能同时兼容这两种工具的注释写法。

　　工具简介——
appledoc：简单方便，适于生成apple风格的html文档，及直接集成到xcode帮助（docset）。官网 http://gentlebytes.com/appledoc/ 。
doxygen：功能强大，适于生成html文档与pdf文档。官网 http://www.stack.nl/~dimitri/doxygen/index.html 。

　　系统环境——
Mac OS X Lion 10.7.5
Xcode 4.6.2
appledoc 2.1
doxygen 1.8.4
MacTeX-2012

一、注释写法

　　提示：这一章主要是参考性内容，比较枯燥。请根据需要来阅读——
对于想简单学一下注释写法的，读前4节就行了；
对于想全面学习appledoc与doxygen均兼容的注释写法的，读前6节就行了；
对于既想使用appledoc，又想使用doxygen增强效果的，请阅读所有的节。

1.1 注释形式

　　标准C/C++的注释形式有“//”形式的单行注释 与“/* */”形式的多行注释这两种。
　　而appledoc与doxygen的文档化注释是它们的变种，有多种形式。例如appledoc与doxygen均兼容的注释形式有以下7种——

/// Single line comment.

/// Single line comment spreading
/// over multiple lines.

/** Single line comment. */

/** Single line comment spreading
 * over multiple lines.
 */

/** Single line comment spreading
 over multiple lines. No star.
 */

/*! Single line comment. */

/*! Single line comment spreading
 over multiple lines.
 */

 

　　虽然appledoc与doxygen都支持。但在平时编写代码时，为了避免风格杂乱的视觉污染，应该固定使用注释形式。

1.1.1 单行注释

　　在很多时候只需写一个简要描述就够了，这时最好使用单行注释。推荐格式为——

/// 简要描述.

 

　　appledoc与doxygen均会将单行的“///”注释识别为简要描述。兼容性非常高。

　　备注——
1) 文本最好统一以英文句号（.）结尾。这样做有助于代码阅读，明确地得知该段文本已经结束，而且有助于避免乱码时的换行符丢失问题。
2) 不要连续多行使用“///”。doxygen在默认情况下，会将多行的“///”当作详细描述，而没有简要注释. 虽然可以修改doxygen的配置以解决上述问题，但多行“///”本身是违背“简要描述”这个初衷的.

1.1.2 多行注释

　　当需要写详细描述时，这时就需要使用多行注释了。推荐格式为——

/** 简要描述.
 *
 * 详细描述或其他.
 */

 

　　对于appledoc与使用了JAVADOC_AUTOBRIEF参数的doxygen来说，它们均会将注释中的第一段识别为简要描述，然后将后面的段识别为详细描述.

　　其实doxygen的标准多行注释为——

/**
 * @brief 简要描述.
 *
 * 详细描述或其他.
 */

 

　　可惜appledoc对@brief指令的支持存在缺陷——@brief不能出现类、协议的注释中，会导致后续内容丢失。 @brief多行注释仅能安全的用在属性、方法的注释中。

　　备注——
1) 多行注释存在“段”的概念，以内容为空的行作为分段依据。如果没有空行隔开的话，会将连续有内容的行连接起来组成一段.
2) 如果省略中间各行行首的星号（*），appledoc与doxygen也能识别。当考虑到注释缩进、美观性、兼容性，还是建议不要省略行首星号。

1.1.3 行尾注释（仅doxygen）

　　在对枚举、结构体等类型的成员进行注释时，为了使内容更加紧凑，我们一般喜欢在行尾写注释。
　　可惜目前仅有doxygen支持行尾注释，而appledoc不支持。

　　doxygen支持以下4种行尾注释——

/**< 行尾注释1. appledoc不支持会变为下一项的注释, doxygen 支持, 根据英文句号自动切分简要描述与详细描述. */
/*!< 行尾注释2. appledoc不支持会变为下一项的注释, doxygen 支持, 会全部当作详细描述, 而缺少简要描述. */
///< 行尾注释3. appledoc不支持会变为下一项的注释, doxygen 支持.
//!< 行尾注释4. appledoc不支持会会忽略, doxygen 支持.

 

　　为了避免appledoc误将行尾注释当作下一项的注释，故推荐第4种注释——既以“//!<”开头的注释。

1.2 类（协议、分类）的注释

　　对于类（协议、分类）来说，一般只需要写简要描述就行了，这时可以使用单行注释——

/// 文档A.
@interface DocA : NSObject

 

　　当需要留下详细描述时，可换成多行注释——

/** 文档B.
 *
 * 文档B的详细描述.
 */
@interface DocB : NSObject

 

1.3 属性的注释

　　对于属性来说，本来使用行尾注释是最好的，能使内容更加紧凑。可惜目前appledoc不支持行尾注释。只好退而求其次，选择单行注释了——

/// 数值属性.
@property (nonatomic,assign) NSInteger num;

 

　　当需要留下详细描述时，可换成多行注释——

/**
 * @brief 字符串属性.
 *
 * 属性的详细描述.
 */
@property (nonatomic,strong) NSString* str;

 

1.4 方法的注释

　　对于没有参数、返回值的简单方法，可以使用单行注释——

/// 简单方法.
- (void)someMethod;

 

　　若方法具有参数或返回值，这时就得使用多行注释了——

/**
 * @brief 带整数参数的方法.
 *
 * @param  value 值.
 *
 * @return 返回value.
 */
- (int)someMethodByInt:(int)value;

 

　　指令说明——
@param : 参数描述.
@return : 返回值描述.

　　由于方法注释需要填写的内容较多（参数列表与返回值等），所以现在有很多插件可以帮忙生成方法的注释，而这些插件一般是使用@brief多行注释的。例如参考文献中的《Xcode4快速Doxygen文档注释 — 简明图文教程（3分钟后爽歪歪）》.

　　在某些时候，我们还需要在方法注释种填写异常、参见、警告 等信息——

/**
 * @brief 带字符串参数的方法.
 *
 * @param  value 值.
 *
 * @return 返回value.
 *
 * @exception NSException 可能抛出的异常.
 *
 * @see someMethod
 * @see someMethodByInt:
 * @warning 警告: appledoc中显示为蓝色背景, Doxygen中显示为红色竖条.
 * @bug 缺陷: appledoc中显示为黄色背景, Doxygen中显示为绿色竖条.
 */
- (NSString*)someMethodByStr:(NSString*)value;

 

　　指令说明——
@exception : 异常描述.
@see : 参见. 具体用法详见 1.5.2 @see、@sa（参见） .
@warning : 警告.
@bug : 警告.

1.5 appledoc、doxygen均支持的指令

　　指令一般以“@”开头，也可以使用“\”等符号开头。 若想在文本中使用“@”、“\”等符号，可使用“\”转义符，例如“\@”、“\\”等。

1.5.1 指令列表

　　指令在appledoc中被称作“Directive”，而在doxygen中被称作“Command”。
　　appledoc没有专门指令参考文档，仅在《Comments formatting style》中给了几个简单示例。
　　而doxygen有详细的指令参考文档，详见《Special Commands》。

　　经过测试，我发现下列指令在appledoc与doxygen中均是有效的——
@brief