Emacs: doxymacs package

This article will describe using doxymacs package which provides template of doxygen comment with key bindings.

1 Install doxymacs package

Download archive from Doxymacs page. Download patch from NetBSD page for compiling with Clang.

$ tar zxf doxymacs-1.8.0.tar.gz
$ cd doxymacs-1.8.0
$ DOXYMACS=http://ftp.netbsd.org/pub/pkgsrc/current/pkgsrc/devel/doxymacs
$ wget ${DOXYMACS}/patches/patch-c_Makefile.in
$ wget ${DOXYMACS}/patches/patch-c_doxymacs__parser.c
$ patch -p0 < patch-c_Makefile.in
$ patch -p0 < patch-c_doxymacs__parser.c
$ ./configure --prefix=${HOME}
$ make all install

The following files are installed.


Move doxymacs_parser to PATH location. Move *.el and *.elc to your location of emacs load-path.

2 ${HOME}/.emacs

Load doxymacs with require. Add doxymacs-mode to your major mode. This article adds it to c-mode-common-hook which is common major mode of C and C++.

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

doxymacs-doxygen-style is variable for doxygen style. This article will set "JavaDoc" to doxymacs-doxygen-style.

(setq doxymacs-doxygen-style "JavaDoc")
"JavaDoc" /**
  * JavaDoc.
"Qt" //!
"C++" /
  / C++.

3 key bindings

I am using the following key bindings.

C-c d i File header comment
C-c d f Function comment
C-c d m Multiple line comment
C-c d s Single line comment
C-c d ; Member fileds comment

3.1 File header comment

File header comment is generated by C-c d i.

 * @file   comment.cc
 * @author username <mail@address>
 * @date   Wed Sep  2 18:46:39 2015
 * @brief

Cursor will be moved to @brief. @auther are set variables of user-full-name and user-mail-address. These variables can be set in ${HOME}/.emacs.

 '(user-full-name "username")
 '(user-mail-address "mail@address")

3.2 Function comment

Function comment is generated by C-c d f.

 * @param string
void foo::set(const std::string &string)

Cursor will be moved to second line.

3.3 Multiple line comment

Multiple line comment is generated by C-c d m.


Cursor will be moved to second line.

3.4 Single line comment

Single line comment is generated by C-c d s.


Cursor will be moved to after /.

3.5 Member field comment

Member field comment is generated by C-c d ;.

std::string mString;          /**<  */

Cursor will be moved to inside of comment.

4 Custom template comment

Custom template comment by below variable in ${HOME}/.emacs.

doxymacs-file-comment-template File header comment
doxymacs-function-comment-template Function comment
doxymacs-blank-multiline-comment-template Multiple line comment
doxymacs-blank-singleline-comment-template Single line comment
doxymacs-member-comment-start Start of member field comment
doxymacs-member-comment-end End of member field comment

This article changes single line comment from "/" to "/**". The n means new line and the p means cursor position.

(defconst doxymacs-my-blank-singleline-comment-template
 '("/** " p " */" >)
 "Default my-style template for a blank singleline doxygen comment.")

This comment is created from JavaDoc template comment. JavaDoc template comment is defined in doxymacs.el.


4.1 My custom template comment

I am using below custom template comment which is set in ${HOME}/.emacs.

(defconst doxymacs-my-file-comment-template
 '("/**" > n
   " * " (doxymacs-doxygen-command-char) "file      "
   (if (buffer-file-name)
       (file-name-nondirectory (buffer-file-name))
     "") > n
   " * " (doxymacs-doxygen-command-char) "author    "
   (user-full-name) (doxymacs-user-mail-address) > n
   " * " (doxymacs-doxygen-command-char) "copyright "
   "(c) 2015 " (user-full-name) ". All right reserved." > n
   " *" > n
   " * " (doxymacs-doxygen-command-char) "brief     "
   (p "Brief description of this file: ") > n
   " */" >)
 "Default my template for file documentation.")

(defconst doxymacs-my-function-comment-template
 '((let ((next-func (doxymacs-find-next-func)))
     (if next-func
    "/**" '> 'n
    " * " 'p '> 'n
    (doxymacs-parm-tempo-element (cdr (assoc 'args next-func)))
    (unless (string-match
                   (regexp-quote (cdr (assoc 'return next-func)))
      '(l " * " (doxymacs-doxygen-command-char)
    "return " (p "Returns: ") > n))
    " */" '>)
   (error "Can't find next function declaration.")
 "Default my-style template for function documentation.")

(defconst doxymacs-my-blank-multiline-comment-template
 '("/**" > n "* " p > n "*/" >)
 "Default my-style template for a blank multiline doxygen comment.")

(defconst doxymacs-my-blank-singleline-comment-template
 '("/** " p " */" >)
 "Default my-style template for a blank singleline doxygen comment.")

 '(doxymacs-file-comment-template doxymacs-my-file-comment-template)