这些小活动你都参加了吗?快来围观一下吧!>>
电子产品世界 » 论坛首页 » 综合技术 » [原创]使用refgen提取C代码中的文档

共1条 1/1 1 跳转至

[原创]使用refgen提取C代码中的文档

菜鸟
2004-02-13 17:53:08     打赏
作者: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]



关键词: 原创     使用     refgen     提取     代码     中的     文档         

共1条 1/1 1 跳转至

回复

匿名不能发帖!请先 [ 登陆 注册 ]