作者：phantom Email：grant_shao@sina.com 转载请注明出处 我们多数是在VxWorks上做开发的程序员，平时需要查看什么函数的说明，一般我们会到docs目录下查看函数说明。里面几乎包罗了VxWorks的所有用得到的函数说明。细心的人一定发现了这些文档的内容其实和VxWorks代码C文件中的一些注释部分是一模一样的，这些说明文档其实就是用TCL脚本工具refgen从C代码中提取的。如何做出象WindRiver一样的C文档是我们今天的话题。

其实这种从代码注释中提取文档的形式并不稀奇，JAVA，C++都有类似的工具。好处自然多了，首先它尽量避免了所见即所得文档模板的问题，其次是保证代码了的说明文档与代码开发的同步，还有其它的好处就不一一讲了。那么如何写一个可以提取文档得C代码呢。请看下面这个模板。

/* file.c - 该文件(库)的描述 */ /*
DESCRIPTION
这里可以写详细的文件说明或对库函数做整体的描述。(DESCRIPTION应该全是大写的，这个网页显示的不对头) NOTE
其实这里没有什么关键字之类的说法，只要是一行开头字母大写的，就会作为黑体字。 LINE
即使
这些文字不
在
一行，但refgen也会将它们生成到一个段落中去的。 \cs
为了将
行按原来意思分
开，可以
这么写，这在添加示例代码时很有用。否则代码都会挤到一行去。
memcpy(Mac, mac, 6); /@ 注意注释在这里是如何写的 @/
fucn(Mac); /@ @会在提取时转换为*的 @/
\ce CAVEATS
也可以写一些警告的语句。 ATTENTION
注意这里没有see also，但实际上隐含了个see also，可以对照实际的效果看看。
*/ /*******************************************************************************
*
* func - 这里写函数的简要说明
*
* 这里再写函数的详细说明。函数的详细说明前面不需要DESCRIPTION做头，默认
* 第一句便是DESCRIPTION。
* 参数说明一般写在DESCRIPTION里面，有两种写法，可以这样写：
* \is
* \i <x>
* 参数一，(注意上面的参数是如何变成斜体的)
* \i <y>
* 参数二
* \ie
* 也可以这样写，不过要比前一种难看多了：
* \ml
* \m <x> -
* 参数一，
* \m <y> -
* 参数二。
* \me
*
* TABLE
* 可以画一个简单的表格。
* \ts
* Key | Name | Meaning
* ----|------------|------------
* | ampersand | bitwise AND
* \| | stile | bitwise OR
* # | octothorpe | bitwise NAND
* \te
*
* RETURNS: N/A
*/ void func
(
char *x, /* 参数说明会被提取出来 */
char *y /* 参数二 */
)
{
/* 代码中的注释是不会被提取出来的 */
return;
} 既然代码已经有了，大家可以直接将代码拷贝出来，就放到你的bsp目录下，让我们先来试一下。cd进bsp目录之间不要忘了运行bin目录下的torvars.bat来设置环境变量。在你的bsp目录下，使用refgen file.c。这时file.html便生成了。
打开生成的html文件，感觉光秃秃的......对了，少了链接。再输入htmlLink命令，这时又生成了另外两个文件：libIndex.html，rtnIndex.html。再打开看看，链接一应俱全。 下面是生成文档的预览

---

Wind River Systems Reference Manual : Wind River Systems Reference Libraries

file

NAME

file - 该文件(库)的描述

ROUTINES

func( ) - 这里写函数的简要说明

DESCRIPTION

这里可以写详细的文件说明或对库函数做整体的描述。(DESCRIPTION应该全是大写的，这个网页显示的不对头)

NOTE

其实这里没有什么关键字之类的说法，只要是一行开头字母大写的，就会作为黑体字。

LINE

即使这些文字不在一行，但refgen也会将它们生成到一个段落中去的。

 为了将
 行按原来意思分
 开，可以
 这么写，这在添加示例代码时很有用。否则代码都会挤到一行去。
 memcpy(Mac, mac, 6);        /* 注意注释在这里是如何写的 */
 fucn(Mac);                  /* @会在提取时转换为*的     */
 

CAVEATS

也可以写一些警告的语句。

ATTENTION

注意这里没有see also，但实际上隐含了个see also，可以对照实际的效果看看。

SEE ALSO

file

---

Wind River Systems Reference Libraries : Routines

func( )

NAME

func( ) - 这里写函数的简要说明

SYNOPSIS

void func
    (
    char * x, /* 参数说明会被提取出来 */
    char * y  /* 参数二 */
    )

DESCRIPTION

这里再写函数的详细说明。函数的详细说明前面不需要DESCRIPTION做头，默认第一句便是DESCRIPTION。参数说明一般写在DESCRIPTION里面，有两种写法，可以这样写：

x

参数一，(注意上面的参数是如何变成斜体的)

y

参数二

也可以这样写：

x -	参数一，
y -	参数二。

TABLE

可以画一个简单的表格。

Key	Name	Meaning
	ampersand	bitwise AND
|	stile	bitwise OR
#	octothorpe	bitwise NAND

RETURNS

N/A

SEE ALSO

file

以上只是简单说明，要想从一批文件中提取文档，做好还是写一个批处理来做。
要想更详细的了解，可以查看Tornado的联机文档。books.html->Tornado Reference->Tornado Utilities->htmlBook/htmlLink/refgen。
祝大家早日炼成文档神功，成为一个优秀的程序员。 [align=right][color=#000066][此贴子已经被作者于2004-2-13 17:39:42编辑过][/color][/align]