Objective-C文档注释

本文转自zyl910

同时兼容appledoc(docset、html)与doxygen(html、pdf)的文档生成

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

工具简介

appledoc:简单方便,适于生成apple风格的html文档,及直接集成到xcode帮助(docset).
doxygen:功能强大,适于生成html文档与pdf文档.

系统环境

  • 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增强效果的,请阅读所有的节。

注释形式

标准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都支持。但在平时编写代码时,为了避免风格杂乱的视觉污染,应该固定使用注释形式.

单行注释

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

/// 简要描述.

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

备注

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

多行注释

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

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

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

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

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

备注

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

行尾注释(仅doxygen)

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

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

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

类(协议、分类)的注释

对于类(协议、分类)来说,一般只需要写简要描述就行了,这时可以使用单行注释:

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

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

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

未完待续…