# comment

**Repository Path**: hdchneg/comment

## Basic Information

- **Project Name**: comment
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2015-06-09
- **Last Updated**: 2020-12-19

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 注释

手工写文档是一件苦差事，幸好现在有从源码中抽取注释生成文档的专用工具。对于 Objective-C 来说，目前最好用的工具是 appledoc 和 doxygen。
可是这两种工具对于注释的要求略有区别。

## 注释写法

## 注释形式

标准C/C++的注释形式有“//”形式的单行注释 与“/* */”形式的多行注释这两种。
而appledoc与doxygen的文档化注释是它们的变种，有多种形式。例如appledoc与doxygen均兼容的注释形式有以下7种:
``` C++
/// 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 都支持，但在平时编写代码时，为了避免风格杂乱的视觉污染，应该固定使用注释形式。

### 单行注释

在很多时候只需写一个简要描述就够了，这时最好使用单行注释，推荐格式为:
``` C++
/// 简要描述.
```
如果是 Linux C 不支持 C++ 注释的，只能使用:
```
/** 简要描述. */
```

### 行尾注释

在对枚举、结构体等类型的成员进行注释时，为了使内容更加紧凑，我们一般喜欢在行尾写注释。
doxygen支持以下4种行尾注释:
``` C++
/**< 行尾注释1. */
/*!< 行尾注释2. */
///< 行尾注释3.
//!< 行尾注释4.
```
推荐使用第4种：
```
//!< 行尾注释4.
```

### 多行注释

当需要写详细描述时，这时就需要使用多行注释了，格式为:
``` C++
/** 简要描述.
 *
 * 详细描述或其他.
 */
```

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

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

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

对于类（协议、分类）来说，一般只需要写简要描述就行了，这时可以使用单行注释——
``` C++
/// 文档A.
@interface DocA : NSObject
```

当需要留下详细描述时，可换成多行注释——
```
/** 文档B.
 *
 * 文档B的详细描述.
 */
@interface DocB : NSObject
```


## 属性的注释

对于属性来说，本来使用行尾注释是最好的，能使内容更加紧凑。可惜目前appledoc不支持行尾注释。只好退而求其次，选择单行注释了:
``` C++
/// 数值属性.
@property (nonatomic,assign) NSInteger num;
```

当需要留下详细描述时，可换成多行注释:
``` C++
/**
 * @brief 字符串属性.
 *
 * 属性的详细描述.
 */
@property (nonatomic,strong) NSString* str;
```

## 方法的注释

对于没有参数、返回值的简单方法，可以使用单行注释:
```
/// 简单方法.
- (void)someMethod;
```

若方法具有参数或返回值，这时就得使用多行注释了:
```
/**
 * @brief 带整数参数的方法.
 *
 * @param  value 值.
 *
 * @return 返回value.
 */
- (int)someMethodByInt:(int)value;
```

在某些时候，我们还需要在方法注释种填写异常、参见、警告 等信息:
```
/**
 * @brief 带字符串参数的方法.
 *
 * @param  value 值.
 *
 * @return 返回value.
 *
 * @exception NSException 可能抛出的异常.
 *
 * @see someMethod
 * @see someMethodByInt:
 * @warning appledoc中显示为蓝色背景, Doxygen中显示为红色竖条.
 * @bug appledoc中显示为黄色背景, Doxygen中显示为绿色竖条.
 */
- (NSString*)someMethodByStr:(NSString*)value;
```

### 文件头

一般格式为:
/**
 * @file    MyDocViewController.h
 * @brief    主页面.
 * @author    [hudongcheng](http://www.pantum.com/)
 * @version    1.0
 * @date    2015-06-09
 *
 * # update （更新日志）
 *
 * [2015-06-09] <hudongcheng> v1.0
 *
 * + v1.0版发布.
 *
 */


## 例子
下面以 faxlib 作为例子，改写该文档的注释，原来的代码如下：

```
typedef enum _FAX_ERROR
{
    ERR_SUCCESS = 0,     // 成功
    ERR_CONNECT = 1,     // 链接失败/未连接设备
    ERR_NON_EXISTEN = 2, // 地址不存在
    ERR_BMP = 3,         // bmp文件格式错误
    ERR_TIFF = 4,        // tiff文件生成失败
    ERR_DEVICE_BUSY = 5, // 设备忙
    ERR_PARMP = 6,       // 参数错误
    ERR_TEMP = 7,        // 缓存目录不可用
    ERR_MEM_APPLY = 8,   // 内存申请失败
    ERR_ERROR = 9,       // 内部错误
    ERR_IMG = 10,        // 不支持的图像类型
    ERR_FAIL = -1,        // 传真失败
}
FAX_ERROR;


/////////////////////////////////////////////////
//
// Function:    Search
// Description: 搜索传真设备
// Input:       NULL
// Output:      pDevice:设备信息
//              deviceCount:搜索到的设备个数
// Return:      成功返回ERR_SUCCESS,失败返回错误代码
//
/////////////////////////////////////////////////
int Search(DeviceInfo *pDevice,
           int *deviceCount);


/////////////////////////////////////////////////
//
// Function:    SetJobSetting
// Description: 填写作业设置，只调用一次设置正份作业
// Input:       totalPages:传真作业总页面数
//              resolusion:作业分辨率
//              pagesize:纸型
//              calCount:传真号码个数
//              phoneNum:保存传真号码的数组，最大99个
//                       号码，每个号码最长32个字节
//              tmpPath:指向缓存文件夹地址的指针
// Output:      NULL
// Return:      成功返回ERR_SUCCESS，失败返回错误代码
//
/////////////////////////////////////////////////
int SetJobSetting(short totalPages,
                  short resolution,
                  short pagesize,
                  short calCount,
                  unsigned char *phoneNum,
                  const char *tmpPath);


/////////////////////////////////////////////////
//
// Function:    SetPagesSetting
// Description: 填写页面设置，循环调用以设置每个页面
// Input:       rawData:指向raw数据的指针
//              rawBits:raw数据位深
//              rawWidth:raw数据宽,单位像素
//              rawHeight:raw数据高,单位像素
//              curPage:当前页码（从0开始）
// Output:      NULL
// Return:      成功返回ERR_SUCCESS，失败返回错误代码
//
/////////////////////////////////////////////////
int SetPagesSetting(char *rawData,
                    short rawBits,
                    short rawWidth,
                    short rawHeight,
                    short curPage);


/////////////////////////////////////////////////
//
// Function:    InitFax
// Description: 初始化设备
// Input:       ipAddr:指向指定设备ip地址的指针
// Output:
// Return:      成功返回ERR_SUCCESS,失败返回错误代码
//
/////////////////////////////////////////////////
int InitFax(char *ipAddr);


/////////////////////////////////////////////////
//
// Function:    SendJobToFax
// Description: 发送作业到指定设备
// Input:       NULL
// Output:      NULL
// Return:      成功返回ERR_SUCCESS，失败返回错误代码
//
/////////////////////////////////////////////////
int SendJobToFax();


/////////////////////////////////////////////////
//
// Function:    CloseFax
// Description: 取消作业发送
// Input:       NULL
// Output:      NULL
// Return:      成功返回ERR_SUCCESS，失败返回错误代码
//
/////////////////////////////////////////////////
int CloseFax();

```


修改注释后，可以在 xcode 的右侧看到帮助信息，代码如下：
```
/**
 * Fax error code
 */
typedef enum _FAX_ERROR
{
    ERR_SUCCESS = 0,     //!< 成功
    ERR_CONNECT = 1,     //!< 链接失败/未连接设备
    ERR_NON_EXISTEN = 2, //!< 地址不存在
    ERR_BMP = 3,         //!< bmp文件格式错误
    ERR_TIFF = 4,        //!< tiff文件生成失败
    ERR_DEVICE_BUSY = 5, //!< 设备忙
    ERR_PARMP = 6,       //!< 参数错误
    ERR_TEMP = 7,        //!< 缓存目录不可用
    ERR_MEM_APPLY = 8,   //!< 内存申请失败
    ERR_ERROR = 9,       //!< 内部错误
    ERR_IMG = 10,        //!< 不支持的图像类型
    ERR_FAIL = -1,       //!< 传真失败
}
FAX_ERROR;


/**
 * @brief 搜索传真设备.
 *
 * @param  pDevice 设备信息
 * @param  deviceCount 搜索到的设备个数
 *
 * @return 成功返回 ERR_SUCCESS，失败返回错误代码.
 */
int Search(DeviceInfo *pDevice,
           int *deviceCount);


/**
 * @brief 填写作业设置，只调用一次设置正份作业.
 * 
 * @param totalPages 传真作业总页面数
 * @param resolusion 作业分辨率
 * @param pagesize 纸型
 * @param calCount 传真号码个数
 * @param phoneNum 保存传真号码的数组，最大99个号码，每个号码最长32个字节
 * @param tmpPath 指向缓存文件夹地址的指针
 *
 * @return 成功返回ERR_SUCCESS，失败返回错误代码
 */
int SetJobSetting(short totalPages,
                  short resolution,
                  short pagesize,
                  short calCount,
                  unsigned char *phoneNum,
                  const char *tmpPath);

/**
 * @brief 填写页面设置，循环调用以设置每个页面
 *
 * @param rawData 指向raw数据的指针
 * @param rawBits raw数据位深
 * @param rawWidth raw数据宽,单位像素
 * @param rawHeight raw数据高,单位像素
 * @param curPage 当前页码（从0开始）
 *
 * @return 成功返回ERR_SUCCESS，失败返回错误代码
 */
int SetPagesSetting(char *rawData,
                    short rawBits,
                    short rawWidth,
                    short rawHeight,
                    short curPage);

/**
 * @brief 初始化设备
 *
 * @param ipAddr 指向指定设备ip地址的指针
 *
 * @return 成功返回ERR_SUCCESS,失败返回错误代码
 */
int InitFax(char *ipAddr);


/**
 * @brief 发送作业到指定设备
 *
 * @return 成功返回 ERR_SUCCESS，失败返回错误代码
 */
int SendJobToFax();


/**
 * @brief 取消作业发送
 *
 * @return 成功返回 ERR_SUCCESS，失败返回错误代码
 */
int CloseFax();

```

## 使用doxygen生成html文档

### 生成 Doxyfile
进入`faxlib`目录，输入以下命令生成 Doxyfile：
```
Doxygen -g
```

### 修改配置
修改 Doxyfile：
```
#给出所有文档的输出目录
OUTPUT_DIRECTORY       = doc
#设置使用的语言
OUTPUT_LANGUAGE = Chinese
#指定doxygen分析的输入文件(目录)
INPUT                  = faxlib.h
#提取C方法
EXTRACT_ANON_NSPACES   = YES
```

### 生成 html
输入命令`doxygen`，生成html。