Sofia-SIP辅助文档五 - 文档

 http://sofia-sip.sourceforge.net/refdocs/docguide.html，翻译自官网的这张网页。

使用Doxygen

Doxygen是一个文档生成程序，被许多C/C++项目采用。它的主页在：http://www.doxygen.org。Sofia的文档也由Doxygen生成。

Doxygen的工作方式就是从C/C++代码中抽取文档数据以及特定的格式化注释。注释也包含一些类似于javadoc的特殊指令。

通常，注释和文档风格应当遵循javadoc风格指南：javadoc style guide。

一条Doxygen注释必须包含它正在描述的实体引用（reference）。例如，描述文件时使用指令@file：

/**
 * @file foo.c
 *
 * Implementation of foo. The foo takes care of grokking xyzzy.
 *
 * @author Jaska Jokunen <jaska.jokunen@company-email.address.hidden> \n
 *
 * @date Created: Wed Oct 20 15:06:51 EEST 2004 jasjoku
 */

通常，被文档化的实体紧跟在注释后。例如，文档化一个函数应当像如下所展示的这样：

/**
 * Orches a candometer. If orching candometer is not possible, it
 * tries to schadule hearping.
 *
 * @param[in]  k        pointer to a candometer
 * @param[in]  level    orching level
 * @param[out] return_hearping return value for schaduled hearping
 *
 * @return
 * The function orch() returns the candometer value, or #ERROR upon an error.
 * If the returned value is 0, the newly schaduled hearping is returned in
 * @a return_hearping.
 */
int orch(cando_t *k, int level, hearping_t *return_hearping)
{
  ...
}

Doxyfile和Doxyfile.conf

doxygen可选项由配置文件Doxyfile指定。作为惯例，某个模块的Doxyfile文件都包含一个通用文件libsofia-sip-ua/docs/Doxyfile.conf。这使得保持模块特定的Doxyfiles尽可能整洁变得可能：

PROJECT_NAME         = "ipt"
OUTPUT_DIRECTORY     = ../docs/ipt

INPUT                = ipt.docs .

@INCLUDE = ../Doxyfile.conf

TAGFILES            += ../docs/docs/doxytags=../docs
TAGFILES            += ../docs/su/doxytags=../su
GENERATE_TAGFILE     = ../docs/ipt/doxytags

从上面这些内容可以观察到一些惯例。Doxygen生成的HMTL文档被放置在顶级目录下的docs子目录下。在docs目录下还将为每个子模块单独创建一个输出目录。在输出目录下针对特定模块的Doxytags被生成放置在doxytags文件内。

<模块名称>.docs文件中的模块文档内容

每个模块都有一个文档，至少包括一个名为<模块名称>.docs的文件。文件内应当包括一些样板化的信息，例如，下面所列的就是文件ipt.docs内的概要信息：

/**
@MODULEPAGE "ipt" - Utility Module

@section ipt_meta Module Meta Information

Utility library for IP Telephony applications.

@CONTACT Pekka Pessi <Pekka.Pessi@nokia-email.address.hidden>

@STATUS @SofiaSIP Core library

@LICENSE LGPL

@section ipt_overview Overview

This module contain some routines useful for IPT applications, like
- ...
- ...
*/

通用Doxygen命令

在这一小节，我们将回顾一遍大部分的Doxygen命令。所有命令在文档中均有说明。命令包括如下这些：

• 风格命令(@a, @b, @c, @e, @em, @p)
• 函数参数和返回值(@param, @return, @retval)

风格命令 - @a, @b, @c, @e

文本风格可通过如下指令更改：@b (粗体字)， @c (代码)，或 @e(斜体字) 。函数参数名使用风格命令@a。

例如，这句："The Content-Type header ct specifies themedia-type of the message body, e.g.,audio/amr would be AMR-encoded audio." 可以用如下所示命令生成

The @b Content-Type header @a ct specifies the @e media-type of
the message body, e.g., @c audio/amr would be AMR-encoded audio.

风格命令可以用别名。例如，@em和@e的用途是相同的，@c和@p的用途也是一样的。.

函数参数和返回值 - @param, @return, @retval

用@param指令文档化函数参数(看看之前的一个orch()函数例子)。作为惯例，数据流方向在@param指令后给出，分别是[in], [out] or [in,out]。

返回值有两种方式表示。一，@return指令，二，retval指令。第二种方式在返回值是一些小数量的可能值时使用（这么翻译？）。例如，枚举类型值或者真假值。

/**Schadule hearping.
 *
 * The function schadule() schadules a hearping.
 *
 * @param[in] h pointer to hearping
 *
 * @retval 0  hearping was successful
 * @retval -1 an error occurred
 */
int schadule(hearping_t *h)
{
  ...
}

例程代码快 - @code, @endcode

一个示例代码块可以被@code和@endcode指令包含。

/**Destroy a hearping.
 *
 * The function hearping_destroy() deinitializes a hearping and
 * reclaims the memory allocated for it.
 *
 * @param[in,out] h pointer to pointer to hearping
 *
 * The function clears the pointer to hearping, so it must be called
 * with a pointer to pointer:
 * @code
 *   hearping_destroy(&x->hearping);
 * @endcode
 */
void hearping_destroy(hearping_t **h)
{

段落

@par指令被用来将文本分隔成各个段落。与@par指令处于同一行的其他文字作为段落的子标题。@date，@note，@bug，@todo，@sa (See Also)和@deprecated这些指令被用来向文档加入一些通用的段落。

文档化文件Documenting Files（这么翻译？）

在大部分文件里都有一个自身文件的文档入口（这句啥意思？）。In most files there is documentation entry for the file itself. 这个入口通常在文档的前部LGPL说明的后面，包括@file指令或者@CFILE/@IFILE。有一些Emacs宏可以用来创建这些范例入口。

分组入口（这么翻译？）

当一篇文档的结构不依从于目录或者文件结构，可以使用分组指令@defgroup和@ingroup。@defgroup指令创建一个新组，@ingroup指令为组增加一个入口（这句啥意思？）。When the structure of the documentation does not follow directory or file structure, it is possible to use grouping commands @defgroup and @ingroup. The command @defgroup creates a group, and @ingroup adds an entry to an group.

创建链接Creating Links

通常，Doxygen在遇到结构体/类时会创建到它们的链接。同样可以为函数、类型名称和变量创建链接。如果函数名后只是一对括号，Doxygen会为函数创建链接。如果类型名称或者变量名前有#，Doxygen也会为它们创建链接。

可以用@link和@endlink指令创建到文档入口的链接，用自由选择链接的方式创建（这句啥意思？）。It is also possible to create links with freely selected link to documentation entries with @link and @endlink commands.

用@ref指令创建到目标为命名页、章节和子章节的链接。

编写文档内容主体（这么翻译？）

一篇文档的主体由@mainpage指令指出。@mainpage入口包括的内容将成为文档集的HTML主页。用Doxygen生成的每个文档集中只能有一个@mainpage指令。@section，@subsection和@subsubsection指令可被用来结构化文档文字。

仍然可以为文档添加单独的HTML页面。可以用@page指令做到这点。这些独立的页面就像@mainpage指令增加的主页一样，他们可以通过导航栏的相关页面链接存取（这句啥意思？）。

添加图片

使用@image指令添加图片。因为不同的文档格式支持不同的图片格式，所以@image指令为每个支持的文档格式指定特定的图片文件。下面的例子展示为HTML文档使用bitmap图片Encapsulate PostScript for print documents（这句啥意思？）：

@image html sip-parser.gif

@image latex sip-parser.eps