使用doxymacs写标准代码注释

首页 > IDE, 初级 > 使用doxymacs写标准代码注释

使用doxymacs写标准代码注释

2010年6月28日 fangzhzh 发表评论阅读评论

doxymacs = doxygen+emacs。
如果你不知道doxygen，请移步这里，或者google之。

doxymacs 官网，现在版本是1.8.0。

特性：

从emacs中，查找某个符号的文档，显示在你选择的浏览器中。
在源代码中方便的插入Doxgen Style格式的注释。
可选：实用外部XML parser加速构建完整列表。
高亮Doxygen关键字。

特性1,3,4我用的比较少，重点介绍第二个。

安装

Doxymacs 依赖一下包:

W3 http://www.cs.indiana.edu/usr/local/www/elisp/w3/docs.html

tempo http://www.lysator.liu.se/~davidk/elisp/

libxml2 http://www.libxml.org/

将doxymacs.el放到load-path路径下，在.emacs中加入下面语句

^?View Code LISP

(require 'doxymacs)

命令doxymacs-mode就可以启动，如让doxymacs-mode随着c/c++ mode自动启动，

^?View Code LISP

(add-hook 'c-mode-common-hook 'doxymacs-mode)

代码中插入doxygen注释

如果一切正常，那么在启动一个c/c++文件后，就进入了doxymacs-mode。
可以使用以下快捷键：

命令	英文解释	中文解释
C-c d ?	will look up documentation for the symbol under the point.	查找当前鼠标点下的符号的文档
C-c d r	will rescan your Doxygen tags file.	重新扫描tags文件
C-c d f	will insert a Doxygen comment for the next function.	为函数插入Doxygen注释
C-c d i	will insert a Doxygen comment for the current file.	为文件插入Doxygen注释
C-c d ;	will insert a Doxygen comment for the current member.	为当前成员插入Doxygen注释
C-c d m	will insert a blank multiline Doxygen comment.	插入多行注释
C-c d s	will insert a blank singleline Doxygen comment.	插入单行注释
C-c d @	will insert grouping comments around the current region.	插入环绕当前区域的注释

到此，doxymacs基本就可以工作正常了。
工作流程如下:


      +------------+            +------------+          +------------+
      |  coding    |----------->| commenting |--------->| generating |
      |            |            |            |          | documents  |
      +------------+            +------------+          +------------+

更改默认doxygen注释样式

方便的插入doxygen注释还不是最精彩的，最精彩的当然是用户自定义样式了。

改变默认的doxygen注释类别

这里我们首先修改变量doxymacs-doxygen-style，doxymacs默认是javaDoc，我们把它改为c++。

定制doxygen的注释模板

doxymacs.el中有定义doxymacs-C++-file-comment-template,blablabla。顾名思义，此物就是c++-file-comment的模板。
比如，根据我们公司注释的规定，我在.emacs中加入如下代码:

^?View Code LISP

(defconst doxymacs-C++-file-comment-template
 '(
   "/******************************************************************************" > n
   "*" > n
   "* " "FILE NAME   :"
   (if (buffer-file-name)
       (file-name-nondirectory (buffer-file-name))
     "") > n
   "*" > n
   "*" " DESCRIPTION :"> n
   "*" > n
   "*" "    "> n
   "*" > n
   "*" " HISTORY     :"> n
   "*" > n
   "*" "    See Log at end of file"> n
   "*" > n
   "*" "Copyright (c) 2006, VIA Technologies, Inc."> n
   "*" "******************************************************************************/"> n)
 "Default C++-style template for file documentation.")

这样，我在test.cpp文件，实用C-c d i，会生成如下代码

^?View Code CPP

/******************************************************************************
 *
 * FILE NAME   :test.cpp
 *
 * DESCRIPTION :
 *
 *
 *
 * HISTORY     :
 *
 *    See Log at end of file
 *
 *Copyright (c) 2006, VIA Technologies, Inc.
 *******************************************************************************/

如果你使用c++的话，你还有下边几个变量需要定制，

变量	作用
doxymacs-C++-function-comment-template	函数
doxymacs-C++-blank-multiline-comment-template	多行注释
doxymacs-C++-blank-singleline-comment-template	单行注释

使用其他语言类同。

enjoy!

GD Star Rating
loading...

标签：C/C++, doxymacs, Emacs, org, 浏览器, 配色, 鼠标

相关日志

分类: IDE, 初级

评论 (16) Trackbacks (1) 发表评论 Trackback

Meteor Liu

2010年6月28日02:17 | #1

回复 | 引用

赞。
不过相比doxymacs，我现在更喜欢用doc-mode。

[回复]
ahei 回复:
六月 28th, 2010 at 2:20 上午
@Meteor Liu, 大概看了下，貌似非常强悍阿，哈，你啥时候有空也写个文章介绍吧

[回复]
fangzhzh 回复:
六月 28th, 2010 at 5:02 上午
@ahei, doc-mode是个什么东东

[回复]
ahei 回复:
六月 28th, 2010 at 5:15 上午
@fangzhzh, google emacs doc-mode

[回复]
fangzhzh 回复:
六月 28th, 2010 at 5:07 上午
@Meteor Liu, 好像没有定制模板的功能啊？

[回复]
Meteor Liu 回复:
六月 28th, 2010 at 5:40 上午
@fangzhzh,
是么？那也有可能。其实doxymacs和doc-mode我都装了但基本不用，功能我也不太了解。
我只是感观上觉得doc-mode默认生成的格式比doxymacs好看点

[回复]
ahei 回复:
六月 28th, 2010 at 5:43 上午
@Meteor Liu, doxymacs可以根据当前函数生成注释的功能还是挺不错的

[回复]
fangzhzh 回复:
六月 28th, 2010 at 6:08 上午
@Meteor Liu, 自己开发就无所谓了，公司开发的话，模板中公司的版权声明很重要哦，嘿嘿。而且基本上每个公司会有自己的注释要求地……

[回复]
vicwjb
2010年6月28日02:27 | #2

回复 | 引用
貌似不支持python阿。。。

[回复]
ahei 回复:
六月 28th, 2010 at 2:50 上午
@vicwjb, 支持阿，

^?View Code TEXT
Doxygen is a documentation system for C++, C, Java, Objective-C, Python, IDL (Corba and Microsoft flavors), Fortran, VHDL, PHP, C#, and to some extent D.

[回复]
BB.QNYD

2010年6月28日04:49 | #3

回复 | 引用

赞！

好东西！

[回复]
SamPeng

2010年6月30日03:13 | #4

回复 | 引用

支持给当前函数加注释时候可以分析这个函数的参数有哪些吗?个人窃以为，加注释的功能最少要有这个功能才算好用。。。不然每次都要写哪些参数太麻烦了

[回复]
ahei 回复:
六月 30th, 2010 at 3:36 上午
@SamPeng, C-c d f will insert a Doxygen comment for the next function. 为函数插入Doxygen注释

[回复]
SamPeng 回复:
七月 1st, 2010 at 2:29 下午
@ahei, 他只能在当前光标出加。。正常得使用肯定时加在函数头。。
就要多一步。跳到函数头再加。。。谢谢了

[回复]
ahei 回复:
七月 2nd, 2010 at 1:24 上午
@SamPeng, 那你写个函数就可以了

[回复]
fangzhzh 回复:
七月 2nd, 2010 at 2:06 上午
@SamPeng, 我一般使用的时候，会C-M-u，Move backward out of one level of parentheses. 往上跳出一层括号，这样一般的c++函数，最多三四次就可以跳到函数体外，光标位于函数头下一行的括号处。

[回复]
ahei 回复:
七月 2nd, 2010 at 2:09 上午
@fangzhzh, C-M-a (M-x c-beginning-of-defun)

[回复]
fangzhzh 回复:
七月 2nd, 2010 at 2:11 上午
@ahei, 我了个去，囧

[回复]
cosmfly

2010年7月5日00:45 | #5

回复 | 引用

嗯，这个功能也不错，不过我感觉不如CEDET中的模板功能强大。

[回复]
匿名

2010年7月5日01:58 | #6

回复 | 引用

请问下，我想doxymacs-C++-function-comment-template中自动添加函数名，取函数名的lisp函数是哪一个啊？

[回复]
ahei 回复:
七月 5th, 2010 at 2:03 上午
@, cedet中应该有，具体的我也不清楚了

[回复]
匿名回复:
七月 5th, 2010 at 2:51 上午
@ahei,
呵呵，已经搞定了，doxymacs里面本来就有。

[回复]
ahei 回复:
七月 5th, 2010 at 2:54 上午
@, 那敢情好，哪个？

[回复]
匿名回复:
七月 5th, 2010 at 4:39 上午
@ahei,
取函数名 (cdr (assoc ‘func (doxymacs-find-next-func)))
返回值是strin

[回复]
匿名

2010年7月5日04:04 | #7

回复 | 引用

取函数名 (cdr (assoc ‘func (doxymacs-find-next-func)))
返回值是string

[回复]
匿名

2010年7月5日14:57 | #8

回复 | 引用

写的不错，支持一下
顺便问一下楼主，我用idlwave mode 的时候有一个绑定的键特不习惯( C+tab )
请问如何取消这个预先绑定，因为这个键我想有其他的用途

谢谢

[回复]
ahei 回复:
七月 6th, 2010 at 1:53 上午
@, 把C+tab绑定到nil上面就可以了

[回复]
fangzhzh 回复:
七月 8th, 2010 at 2:00 上午
@, 我一般都是使用(global-unset-key (kbd “C-tab”))来取消某个键绑定的，不知道合不合理:)

[回复]
owr

2010年7月30日07:49 | #9

回复 | 引用

doxymacs 在给 C/C++ 进行多行注释时，C-c d f 生成注释之后，接下来的话，就不能跟随前行的注释风格了，那个 ‘*’ 号每次还得自己敲，怎样把它给弄成自动的呢？

[回复]
fangzhzh 回复:
七月 30th, 2010 at 7:52 上午
@owr, 不好意思，什么意思呢，能不能给个例子

[回复]
owr

2010年7月30日08:00 | #10

回复 | 引用

比如这个，模板代码是这样，
/**
* @file pagerpc.cpp
* @author
* @date
*
* @brief
*
*
*/
加入我的 brief 一行塞不下的话，需要换行时，摁下之后，就变成了
/**
* @file pagerpc.cpp
* @author
* @date
*
* @brief
the blank line
*
*
*/

而不是理想中的：
/**
* @file pagerpc.cpp
* @author
* @date
*
* @brief
*
*
*
*/
请问这个怎么解决，谢谢！

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:10 上午
@owr, 默认的模板生成以后，就和doxymacs就没有关系了。再输入的什么的话，就归cc-mode来解释并管理了。如果要实现你要的功能的话，我觉得写个lisp函数是可以实现，但那样的话，太暴力了，我想你也是希望一个比较优雅的方案，容我考虑一下。

[回复]
ahei 回复:
七月 30th, 2010 at 8:12 上午
@fangzhzh, 我记得Emacs内置是可以弄的,忘记怎么弄了

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:13 上午
@ahei, 上manul

[回复]
ahei 回复:
七月 30th, 2010 at 8:14 上午
@fangzhzh, 我都忘记了,上啥manual

[回复]
owr 回复:
七月 30th, 2010 at 8:21 上午
@fangzhzh,
呵呵，谢谢啦。继续 hack ahei 大神的配置文件，好久没更新了。。。

[回复]
ahei 回复:
七月 30th, 2010 at 8:28 上午
@owr, 呵呵, 最近有点忙,等闲下来继续跟进

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:25 上午
@owr, 搞定，`M-j’ (`c-indent-new-comment-line’)

[回复]
ahei 回复:
七月 30th, 2010 at 8:27 上午
@fangzhzh, 这样明显不太方便啊,我记得是直接回车可以搞定的, 而且不在注释里的时候回车也没问题

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:32 上午
@ahei, 使用c-indent-new-comment-line，然后设置 comment-multi-line 为t，就可以了。
manul的解释如下：c-indent-new-comment-line： Break line at point and indent, continuing comment or macro if within one.
。 If inside a comment and `comment-multi-line’ is non-nil, the indentation and line prefix are preserved。

[回复]
ahei 回复:
七月 30th, 2010 at 8:36 上午
@fangzhzh, 但是你在// comment的后面按M-j也会出来//

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:38 上午
@ahei, 是的。这样吧正好是owr的要求吗？

[回复]
ahei 回复:
七月 30th, 2010 at 8:51 上午
@fangzhzh, 不是的,他要的是在
/**
*
*/里面自动加星号, 而不是在//后面自动加双斜线

[回复]
fangzhzh 回复:
七月 30th, 2010 at 8:53 上午
@ahei, /**
*/里面自动加星号, 而不是在//后面自动加双斜线，两个都能干。

[回复]
owr 回复:
七月 30th, 2010 at 9:31 上午
@fangzhzh, 呵呵，还不是太完美，如果直接摁enter
搞定就更好了；还有用 // 单行注释的时候 enter 正常，用 /* */ 多行注释的时候才去
跟随前行格式，包括前行的缩进等。。。

[回复]
ahei 回复:
七月 30th, 2010 at 11:21 上午
@fangzhzh, 关键他只要前者

[回复]