当前位置: 首页 > 工具软件 > Sofia-SIP > 使用案例 >

Sofia-SIP辅助文档五 - 文档

宫子晋
2023-12-01
 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

文本风格可通过如下指令更改:@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



 类似资料: