阅读Sofia-SIP源码五 源码文件文档化的注释

偶然看到Sofia wiki中某一个头文件的文档页面时，突然觉得像是明白了如何在头文件中写那些Doxygen可以使用的注释内容了。就以sofia-sip/su_types.h头文件为例说明。

#ifndef SU_TYPES_H
/** Defined when <sofia-sip/su_types.h> has been included */
#define SU_TYPES_H

上面那张图对应的是上面这段代码。这是介绍头文件卫哨宏。显然文字内容取自注释文字。

#ifndef _INTPTR_T_DEFINED
/** Integer type large enough to store pointers */
typedef SU_INTPTR_T intptr_t;
#endif
#ifndef _UINTPTR_T_DEFINED
/** Unsigned integer type large enough to store pointers */
typedef unsigned SU_INTPTR_T uintptr_t;
#endif

/** 64-bit unsigned integer */
typedef SU_U64_T uint64_t;
/** 64-bit signed integer */
typedef SU_S64_T int64_t;
/** 32-bit unsigned integer */
typedef SU_U32_T uint32_t;
/** 32-bit signed integer */
typedef SU_S32_T int32_t;
/** 16-bit unsigned integer */
typedef SU_U16_T uint16_t;
/** 16-bit signed integer */
typedef SU_S16_T int16_t;
/** 8-bit unsigned integer */
typedef SU_U8_T  uint8_t;
/** 8-bit signed integer */
typedef SU_S8_T  int8_t;

/** At least 64-bit integer */
typedef SU_LEAST64_T int_least64_t;
/** At least 32-bit integer */
typedef SU_LEAST32_T int_least32_t;
/** At least 16-bit integer */
typedef SU_LEAST16_T int_least16_t;
/** At least 8-bit integer */
typedef SU_LEAST8_T int_least8_t;

#ifdef SOFIA_ISIZE_T
/** Compatibility type.
*
* sofia-sip <= 1.12.1 often used int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as int, otherwise as size_t. Note that int is signed and size_t is
* unsigned.
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_ISIZE_T isize_t;
#else
typedef size_t isize_t;
#endif

#ifdef SOFIA_ISSIZE_T
/**Compatibility type.
*
* sofia-sip <= 1.12.1 used int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as int, otherwise as ssize_t. (-1 is used for error indication).
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_ISSIZE_T issize_t;
#else
typedef ssize_t issize_t;
#endif

#ifdef SOFIA_USIZE_T
/**Compatibility type.
*
* sofia-sip <= 1.12.1 sometimes used unsigned int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as unsigned int, otherwise as size_t.
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_USIZE_T usize_t;
#else
typedef size_t usize_t;
#endif

上面两段代码对应的是第二张图。首先，每个typedef的说明文字一定是在这个typedef前面那行的注释内容。再仔细看，每个typedef的说明文字只取紧挨它之前那些注释的第一行注释内容。

/**@file sofia-sip/su_types.h Basic integer types for @b su library.
*
* This include file provides <stdint.h> or <inttypes.h> types.
*
* @author Pekka Pessi <Pekka.Pessi@nokia.com>
* @date Created: Thu Mar 18 19:40:51 1999 pessi
*/

这一部分的注释内容已经多次提到过了。可以明显看到里面的一些用法。例如，@b的作用就是粗体字显示。@author和@date两个是关键字，分别显示成Author：和Date：，且注释中跟在其后的文字会在文档中出现在第二行。

#ifdef SOFIA_SSIZE_T
/** POSIX type used for a count of bytes or an error indication. */
typedef SOFIA_SSIZE_T ssize_t;
#endif

#ifdef SOFIA_ISIZE_T
/** Compatibility type.
*
* sofia-sip <= 1.12.1 often used int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as int, otherwise as size_t. Note that int is signed and size_t is
* unsigned.
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_ISIZE_T isize_t;
#else
typedef size_t isize_t;
#endif

#ifdef SOFIA_ISSIZE_T
/**Compatibility type.
*
* sofia-sip <= 1.12.1 used int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as int, otherwise as ssize_t. (-1 is used for error indication).
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_ISSIZE_T issize_t;
#else
typedef ssize_t issize_t;
#endif

#ifdef SOFIA_USIZE_T
/**Compatibility type.
*
* sofia-sip <= 1.12.1 sometimes used unsigned int for count of bytes.
* When configured for compatibility with sofia-sip 1.12.0, this is defined
* as unsigned int, otherwise as size_t.
*
* @since New in @VERSION_1_12_2.
*/
typedef SOFIA_USIZE_T usize_t;
#else
typedef size_t usize_t;
#endif

最后一张图显示的内容是将上述代码中这三个特殊的typedef进行了不一样的文档展示。首先，注释仍然必须紧挨每个typedef、位于typedef的前面，不在同一行。从现实效果来看，所有的注释内容均显示出来了。而且我们也看到了@since是个关键字，会显示成Since:。并且，注释里紧跟其后的内容会在文档的第二行显示。

在观察su.h头文件时注意到之前没看到过的关键字：@sa。它会被解析成：See also:。同时还注意到，添加超级链接的方式：

<a href="http://msdn.microsoft.com/library/en-us/winsock/winsock/wsabuf_2.asp">WSABUF of WinSock2</a>

用html的a标签包裹需要超级链接的文字。

综观上述几个分析，所有在文档中出现的注释必定是/**开头的注释。如果只是/*开头的注释不会在文档中出现。