doxygen + vim 自动生成C文档教程

doxygen +vim 生成c程序文档
===========================

1. 下载安装doxygen

 

按说明，把相应的信息配好。

第四步就会生成相应的文档。 如果有错，要看输出日志。

2. 编写一个C程序

如下的源程序在vim中打开就像上图一样。

/*doxygen 文档生成说明 {{{ */
/* Copyright (C)
 *
 * XXXXXX
 * All right reserved
 *
 */

/**
 * @file client.c
 * @author  xym
 * @version 1.0
 * @date 2012-04-06
 */

/** @file client.c
  @brief tuxedo的一个客户端实现

  Details.
  */

/** @def  ALLOClEN 80
 * @brief  定义输入和返回的长度*
 */

/**
 * @fn  int tpcall(char *svc, char *idata, long ilen, char **odata, long *olen, long flags)
 * @brief  tpcall
 *
 * @param svc SERVICE的名称
 * @param idata 输入缓冲区的地址，客户端传给服务端的参数放在该缓冲区内
 * @param ilen 输入缓冲区的长度——只有缓冲区类型为CARRAY时才指定长度，其他情况传0
 * @param odata 输出缓冲区的地址，服务端传给客户端的结果放在该缓冲区内
 * @param olen 输出缓冲区的长度
 * @param flags 调用标志
 *
 * @returns   
 */

/**
 * @fn int tpinit(TPINIT *tpinfo)
 * @brief  tpinit 与TUXEDO SERVER建立连接
 *
 * @param tpinfo TPINIT结构体在atmi.h中
 *
 * @returns   失败返回-1, 错误号保存在全局变量tperrno中。
 */

/**
 * @fn void tpfree(char *bufptr)
 * @brief  tpfree
 * @param bufptr 指向要释放的缓冲区首地址的指针
 */
/*}}}*/

#include <stdio.h>
#include "atmi.h"

#define ALLOClEN 80

extern int tpcall(char *svc, char *idata, long ilen, char **odata, long *olen, long flags);
extern int tpinit(TPINIT *tpinfo);
extern void tpfree(char *bufptr)

int main(int argvc, char** agr)
{
    char *inbuf=NULL;
    char *outbuf=NULL;
    long len=0;
    long outlen=0;

    /*tpinit() 客户端调用连接应用{{{*/
    if  (tpinit((TPINIT * )NULL) == -1)
    {
        exit(1);
    } /*}}}*/

    /*tpalloc() 分配一个STRING类型数据缓冲{{{*/
    if (NULL==(inbuf=tpalloc("STRING", NULL, ALLOClEN)))
    {
        tpterm();
        exit(2);
    }

    /*用tpalloc()分配一个STRING类型数据缓冲*/
    if (NULL==(outbuf=tpalloc("STRING", NULL, ALLOClEN)))
    {
        tpterm();
        exit(-1);
    }/*}}}*/

    /*拷贝进缓冲 {{{*/
    strcpy(inbuf,  "ht");
    printf("\t请求报文====>[%s]\n",inbuf);
    /*}}}*/

    /*调用sv_connect 服务 {{{*/
    if ( tpcall("sv_connect", inbuf, 0, &outbuf, &outlen, 0)== -1)
    {
        fprintf(stderr, "sv_connect fail.\n");
        tpfree(inbuf);
        tpfree(outbuf);
        tpterm();
        exit(-1);
    } /*}}}*/

    /*调用sv_chkaccreq 服务{{{*/
    if ( tpcall("sv_chkaccreq", inbuf, 0, &outbuf, &outlen, 0)== -1)
    {
        fprintf(stderr, "service requst fail.\n");
        tpfree(inbuf);
        tpfree(outbuf);
        tpterm();
        exit(-1);
    } /*}}}*/

    /*调用sv_dealaccreq 服务{{{*/
    if ( tpcall("sv_dealaccreq", inbuf, 0, &outbuf, &outlen, 0)== -1)
    {
        fprintf(stderr, "service requst fail.\n");
        tpfree(inbuf);
        tpfree(outbuf);
        tpterm();
        exit(-1);
    } /*}}}*/

    /*输出结果{{{*/
    printf("\n");
    printf("\t返回报文<======[%s]\n", outbuf);
    tpfree(inbuf);
    tpfree(outbuf);
    /*}}}*/

    /*调用tpterm()切断与应用的连接{{{*/
    tpterm();
    exit(0);
}
/* vim:set fdm=marker: */

 
3. 编译生成html
 这里可以使用doxygen的向导工具，生成html,不多说

4. vim的插件DoxygenToolkit.vim 在www.vim.org上下载
安装方法，直接拷到plugin下，_vimrc中增加

"doxygen 使用
":Dox  :DoxLic :DoxAuthor   命令
let g:DoxygenToolkit_commentType = "C"
let g:DoxygenToolkit_briefTag_pre="@brief  "
let g:DoxygenToolkit_paramTag_pre="@param "
let g:DoxygenToolkit_returnTag="@returns   "
let g:DoxygenToolkit_authorTag="@author  "
let g:DoxygenToolkit_dateTag="@date "
let g:DoxygenToolkit_versionTag="@version "
let g:DoxygenToolkit_briefTag_funcName="yes"
let g:doxygen_enhanced_color=1

只要在函数名下键入:Dox就会自动生成一个模板。
要注意，一定要有函数的原型，否则doxygen编译时，会报错的。
例如，clinet.c中加了函数原型


5. 把html中的UTF-8替换成gbk
doxygen生成的html中是用UTF-8的，把它换成gbk,这样可以显示中文。

这里主要用到vim中同时替换多个文件的方法。
:args *.html
:argdo %s/UTF-8/gbk/g | update
解释一下，%表示全文，s表示替换，"/"是分割符，g表示一行中有多个UTF-8一律替换。update表示更新。

我自己写了一个函数：

" 替换utf-8
func Utf8()
    :args *.html
    :argdo %s/UTF-8/love/g | update
endfunction
map <silent> <leader>utf :call Utf8()<enter>
其中<leader>就是"\"的意思，在vim中执行，只要输入\utf即可。

为了让vim自动处理上面的过程，采用vim的一录制脚本的功能。
下面的是man vim 时的内容

 -w {scriptout}
                   All  the characters that you type are recorded in the file
                   {scriptout}, until you exit Vim.  This is  useful  if  you
                   want  to  create a script file to be used with "vim -s" or
                   ":source!".  If the {scriptout}  file  exists,  characters
                   are appended.
只要用下面的命令：
gvim -w configure *.html (路径可以自己加上)
然后输入 :call Utf8(), 回车
然后输入 :q  退出vim

可以打开configure看看，里面记录了刚才的过程。

这样每次需要重复处理时，只要输入：
gvim -s configure *.html  (路径可以自己加上)

6. 如果能在vim中调用doxygen就更好了，自己写了一个bat文件。
@echo off
start "" doxygen D:\doxgen_test\doxyfile
gvim -s configure D:\doxgen_test\html\html\*.html
start "" C:\"Program Files"\"Mozilla Firefox"\firefox D:\doxgen_test\html\html\index.html
exit

解释一下， @echo off是关闭下面的输出信息
start ""是为了执行完后， cmd窗口自动关闭。查了很久才找到这个方法。

这样保存为build.bat, 以后只要双击就可以自动执行。

上面doxyfile是doxygen在用向导时自动生成的文件，是一些配置内容，可以手动改变。

把这些内容加到_vimrc中：
" 替换utf-8
func Utf8()
:args *.html
:argdo %s/UTF-8/love/g | update
endfunction
map <silent> <leader>utf :call Utf8()<enter>
" make 调用外部命令自动关闭cmd
nmap <F8> :silent !make<enter>

这样可以在vim中，直接按F8生成文档，启动firefox，很方便。

解释一下，:silent 是在执行命令时，cmd窗口自动关闭。!是调用外部命令。例如：!dir