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

使用doxymacs写标准代码注释

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中加入下面语句

(require 'doxymacs)

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

(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中加入如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
(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,会生成如下代码

1
2
3
4
5
6
7
8
9
10
11
12
13
14
/******************************************************************************
 *
 * 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!

分享家:Addthis中国
GD Star Rating
loading...
使用doxymacs写标准代码注释, 8.6 out of 10 based on 20 ratings 标签:C/C++, doxymacs, Emacs, org, 浏览器, 配色, 鼠标

相关日志

分类: IDE, 初级
  1. owr
    2010年7月30日08:25 | #1

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

    [回复]

    匿名 回复:

    @owr,

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

    对, 我也失效

    [回复]

    fangzhzh 回复:

    @, 我一般使用toggle-trunk-lines,可以把一行显示为多行,不知道是不是你们要是那种效果。

    [回复]

    owr 回复:

    @owr

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

    [回复]

    fangzhzh 回复:

    @owr, 没有找到sams-lib这个文件…

    [回复]

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

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

    [回复]

    fangzhzh 回复:

    @zhugewei, 1.修改变量doxymacs-doxygen-style,可以使用C-h v查看并custom此变量,doxymacs默认是javaDoc,我们把它改为c++.2 在.emacs中(defconst doxymacs-C++-file-comment-template …)。ahei跟我说过直接修改源文件不是一个好方法,所以对源文件的修改我一般放到.emacs中。

    [回复]

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

    你好,我又来了。

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

    [回复]

    fangzhzh 回复:

    @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 回复:

    @fangzhzh, got it, thanks very much!

    [回复]

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

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

    [回复]

    fangzhzh 回复:

    @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 回复:

    @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 回复:

    @peng, 看来doxygen-style的选择是个普遍性的问题,回头有时间把这个问题在文章中单独列出来吧。谢谢你的反馈。

    [回复]

  5. 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 回复:

    @peng,
    查看一下doxymacs-doxygen-style,如果不是c++,设置(setq doxymacs-doxygen-style “C++”)。

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

    [回复]

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

    w3的链接已经失效了,楼主有备份吗?

    [回复]

    fangzhzh 回复:

    @RMS7, 我感觉你如果用apt,或者yum安装的话,应该依赖软件是不用你安装的

    [回复]

  7. 2014年5月14日17:00 | #7

    com/womensblazerscoatsandjacketsTags plaid coat, orvis coat, levi’s made of wool motor bike coat, unique blazers, layers plus jacketsHow A great deal If you Imagine To pay more for A new Quilted Barbour Coat.

    [回复]

  8. 2016年4月6日11:50 | #8

    Huntsville’s metro area includes Madison and Limestone counties. Decatur on the other side of the river has its own metro area. Metro Mobile is just Mobile County. Fast-growing Baldwin County across the bay also has its own metro designation. http://www.michaelkorsbag.us.org Hutchinson said Friday that failure to authorize funding for the Medicaid expansion would create a budget “hole” of at least $100 million, and “any details will be provided at the budget hearing. u cheap michael kors bags
    He’s a consultant winemaker at Borderland Vineyard, not far from Paradocx. michael kors outlet Mitchell, Turner’s stem cell coordinator at MD Anderson, implied the Gilbert facility has taken the stem cell torch from Good Samaritan.
    On other topics: http://www.coachhandbagsdeal.us.com To this day, property records show that the owner of the . d coach handbags
    MARKET ST. michael kors outlet Pickens, who s been CEO of the Austin, Texas-based company since 2007, owns 4.
    k So that limits what’s available, something rookie Dylan Larkin found out when he prepared for his first training camp with the Red Wings this season. michael kors outlet A judge rejected his request to reduce his $100,000 bond because Randle hadn’t hired an attorney or applied for courtappointed counsel. coach factory outlet
    “For us, it fits in as a Germanic off-dry style of wine, and if you do have people who know anything about Gewurztraminer, they like it. louis vuitton outlet “We work a lot to keep the worst from happening,” Grijalva said. http://www.michaelkorshandbagsbuy.us.com
    Mark Tower covers local government for MLive/The Saginaw News. Contact him at 989-284-4807, by email ator follow him on,or. coach factory outlet Rice of Lakeside Animal Hospital, who has cared for Hank since his arrival in Milwaukee in the spring of 2014, confirmed the identity of Hank in an examination ]” the Brewers said in a statement Friday. s louis vuitton outlet online
    Martin expanded the repertoire, signing comedy acts such as the Goons and some pop singers. cheap louis vuitton bags we just came in too relaxed.
    She’s one of five Arizona kids between the ages of 9 and 12 who are in the midst of the final tallying process to determine the winner of the contest to select the most innovative, delicious and healthy side dish recipe. ray ban sunglasses outlet Saturday in an all6ASouth semifinal matchup.
    “Sharapova has earned $36. coach outlet “___Follow Howard Fendrich on Twitter at http://twitter.
    A speedster who ran the 40-yard-dash in 4. cheap nfl jerseys Wallace said Milligan’s request to hire an attorney isn’t in response to a defamation lawsuit filed by his office’s former outreach manager, David Singer of White Hall, against Milligan and his chief of staff, Jim Harris.
    a Cueto’s struggles began in the first when Manny Machado walked and Chris Davis singled before Jones delivered a towering 450-foot shot to center. michael kors handbags “There’s something about this track.
    This is not a romance but an action-adventure rescue. cheap michael kors bags Without gaining more altitude, the pilot returns to the same airport. z coach bags
    Baltimore’s Tony Donatelli would add to the lead in the fourth with another goal. michael kors bags Mom-and-pop vendors will also offer samples and sell foods like salsa, spice rubs, barbecue and Indian frybread.
    g In communities where housing affordability is a critical issue, Airbnb says, the company will support limiting short-term rentals to primary residences. coach outlet online What does current interest in genealogy say about contemporary culture, of individual and collective identities, of our orientation to the past, to the future? Now, as before, genealogy often reveals more about the genealogists than their ancestors. k
    Which capital region winery can be called — in terms of offerings, atmosphere and environs — the finest? PennLive readers voted, and earned the distinction of michael kors outlet Nettleton, Sr. michael kors bags
    Vanessa Chetney, a 32-year-old Portland resident, plowed her gold into the heavy wooden sign, which proved to be an unyielding match for the two-ton SUV. coach outlet store online FORT SMITH The first of three finalists for the city administrator job took a tour of the city Monday before going into a closed interview with city directors. z michael kors outlet
    She squeezes her hands together tightly – skull ring on her index finger – breathing slowly and laughing all the same http://www.michaelkorshandbagstrade.us.com “Who you know and who they know.
    Javier Serrano and Iberika Sanches to Janisette Dominquez, 128 Newfield Road, $65,000. michael kors outlet The Poteetes were married on Sept. t cheap michael kors bags
    Since its inception in 1936, Bruno Magli? has created refined, handcrafted footwear and fine leather goods for those who appreciate elegant design and impeccable craftsmanship. ray ban outlet There are a lot of people, including myself, who see Princess Leia as George Lucas’ Dejah Thoris.

    [回复]

评论分页
1 2 41433
  1. 2011年7月31日18:44 | #1
:wink: :-| :-x :twisted: :) 8-O :( :roll: :-P :oops: :-o :mrgreen: :lol: :idea: :-D :evil: :cry: 8) :arrow: :-? :?: :!: