使用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

owr

2010年7月30日08:25 | #1

回复 | 引用

还有个 fill-column 的问题，尽管设置 default-fill-column 了，但有时会失效（还是铺满一整行，时灵时不灵），不知道有没有遇到这样的情况。。。

[回复]
匿名回复:
八月 14th, 2010 at 2:18 下午
@owr,

owr :
还有个 fill-column 的问题，尽管设置 default-fill-column 了，但有时会失效（还是铺满一整行，时灵时不灵），不知道有没有遇到这样的情况。。。
[回复]

对, 我也失效

[回复]
fangzhzh 回复:
八月 15th, 2010 at 11:20 下午
@, 我一般使用toggle-trunk-lines，可以把一行显示为多行，不知道是不是你们要是那种效果。

[回复]
owr 回复:
八月 25th, 2010 at 1:44 下午
@owr

少了这个
(require ’sams-lib)
加上去就可以了。。。

[回复]
fangzhzh 回复:
八月 25th, 2010 at 2:43 下午
@owr, 没有找到sams-lib这个文件…

[回复]
zhugewei

2010年9月26日18:06 | #2

回复 | 引用

你好，我是安装了doxymacs之后，将doxymacs.el拷贝到load-path，然后加入你的模板，打开一个.cpp文件，怎么添加注释都是默认java格式。我想要的模板格式是注释第一行至少是多个星号：/***********************************，于是我自己在doxymacs.el中搜索/**，并将它改为/************************************，但最终生成的注释都是“/**”这种格式的。
请问，假如我要修改现有模板或使自定义模板生效，应怎么修改？

[回复]
fangzhzh 回复:
九月 26th, 2010 at 11:26 下午
@zhugewei, 1.修改变量doxymacs-doxygen-style,可以使用C-h v查看并custom此变量，doxymacs默认是javaDoc，我们把它改为c++.2 在.emacs中(defconst doxymacs-C++-file-comment-template …）。ahei跟我说过直接修改源文件不是一个好方法，所以对源文件的修改我一般放到.emacs中。

[回复]
zhugewei

2010年10月28日15:21 | #3

回复 | 引用

你好，我又来了。

在写函数注释时，你文档中所描述的注释方式中没有像自动列出参数名一样自动列出函数名。
我想问一下，是否有类似的定义？

[回复]
fangzhzh 回复:
十月 28th, 2010 at 8:24 下午
@zhugewei, (defconst doxymacs-C++-function-comment-template
‘((let ((next-func (doxymacs-find-next-func)))
(if next-func
(list
‘l
“/// ” (cdr (assoc ‘func (doxymacs-find-next-func)))
“/// ” ‘p ‘> ‘n
“///” ‘> ‘n
(doxymacs-parm-tempo-element (cdr (assoc ‘args next-func)))
(unless (string-match
(regexp-quote (cdr (assoc ‘return next-func)))
doxymacs-void-types)
‘(l “///” > n “/// ” (doxymacs-doxygen-command-char)
“return ” (p “Returns: “) > n))
“///” ‘>)
(progn
(error “Can’t find next function declaraton.”)
nil))))
“Default C++-style template for function documentation.”)

把我给出的函数和doxymacs.el中的函数对比一下，就知道改起来很简单。不过，我知道我的方法肯定不是最好的，坐等优雅方案。

[回复]
zhugewei 回复:
十月 30th, 2010 at 1:27 下午
@fangzhzh, got it， thanks very much！

[回复]
peng

2011年8月1日16:07 | #4

回复 | 引用

您好，我将(defconst doxymacs-C++-file-comment-template
代码，放到了~/.emacs中，重新启动emacs。
使用C-c d i不过为啥，加载的还是以前默认的注释，而不是配置文件中的信息。
这是为啥？等待您的回复。

[回复]
fangzhzh 回复:
八月 1st, 2011 at 4:15 下午
@peng, 两种可能：第一种，是不是你这个定义要放到(require ‘doxmacs)后边呢，这个我具体不太清楚。第二个可能，你的doxygen-style可能设置的是java的，那么修改方案是： 1.修改变量doxymacs-doxygen-style,可以使用C-h v查看并custom此变量，doxymacs默认是javaDoc，我们把它改为c++.2 在.emacs中(defconst doxymacs-C++-file-comment-template …）。

试试看

[回复]
peng 回复:
八月 2nd, 2011 at 11:16 上午
@fangzhzh,
谢谢您，根据您的回复，我的emacs中的doxymacs-doxygen-style是默认的javaDoc.
我试着在~/.emacs文件中，设置了该变量的值，代码如下：

;;加载doxymacs的相关配置(编写注释时使用)
(add-to-list ‘load-path “~/.emacs.d/doxymacs-1.8.0″)

(require ‘doxymacs)
(add-hook ‘c-mode-common-hook ‘doxymacs-mode);;启动doxymacs-mode
(add-hook ‘c++-mode-common-hook ‘doxymacs-mode) ;;启动doxymacs-mode
(setq doxymacs-doxygen-style “C++”)

然后将模板加入到后面，重启emacs。
现在可以使用自定义的模板了。

[回复]
fangzhzh 回复:
八月 2nd, 2011 at 11:20 上午
@peng, 看来doxygen-style的选择是个普遍性的问题，回头有时间把这个问题在文章中单独列出来吧。谢谢你的反馈。

[回复]
peng

2011年8月2日16:02 | #5

回复 | 引用

您好：
我在~/.emacs文件中添加了如下的脚本代码

(defconst doxymacs-C++-function-comment-template
‘((let ((next-func (doxymacs-find-next-func)))
(if next-func
(list
‘l
“/** ” ‘> ‘n
” * ” ‘p ‘> ‘n
” * ” ‘> ‘n
(doxymacs-parm-tempo-element (cdr (assoc ‘args next-func)))
(unless (string-match
(regexp-quote (cdr (assoc ‘return next-func)))
doxymacs-void-types)
‘(l
” * ” > ‘n
” * ” (doxymacs-doxygen-command-char)
“return ” (p “Returns: “) > n))
” */” ‘>)
(progn
(error “Can’t find next function declaration.”)
nil))))
“Default C++-style template for function documentation.”)
可对cpp文件 /**
*
*
/// @param bb
/// @param cc
*
* @return
*/
int aa(QString bb, QString cc); 中添加的注释是如下形式，我没有学习过elisp语言，您看是那里的原因造成的？

[回复]
fangzhzh 回复:
八月 2nd, 2011 at 6:11 下午
@peng,
查看一下doxymacs-doxygen-style，如果不是c++，设置(setq doxymacs-doxygen-style “C++”)。

我也不太懂elisp，不过是不是这个原因呢？因为你上一次的留言已经说解决这个问题了

[回复]
RMS7

2012年4月26日16:06 | #6

回复 | 引用

w3的链接已经失效了，楼主有备份吗？

[回复]
fangzhzh 回复:
四月 26th, 2012 at 4:16 下午
@RMS7, 我感觉你如果用apt,或者yum安装的话,应该依赖软件是不用你安装的

[回复]