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.

${HOME}/bin/doxymacs_parser
${HOME}/share/emacs/site-lisp/xml-parse.el
${HOME}/share/emacs/site-lisp/xml-parse.elc
${HOME}/share/emacs/site-lisp/doxymacs.el
${HOME}/share/emacs/site-lisp/doxymacs.elc

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"	//!
	/*!
	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.

(custom-set-variables
 '(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.")

(custom-set-variables
 '(doxymacs-blank-singleline-comment-template
   doxymacs-my-blank-singleline-comment-template)
)

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

doxymacs-JavaDoc-file-comment-template
doxymacs-JavaDoc-function-comment-template
doxymacs-JavaDoc-blank-multiline-comment-template
doxymacs-JavaDoc-blank-singleline-comment-template

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
   (list
    'l
    "/**" '> 'n
    " * " 'p '> 'n
    (doxymacs-parm-tempo-element (cdr (assoc 'args next-func)))
    (unless (string-match
                   (regexp-quote (cdr (assoc 'return next-func)))
                   doxymacs-void-types)
      '(l " * " (doxymacs-doxygen-command-char)
    "return " (p "Returns: ") > n))
    " */" '>)
       (progn
   (error "Can't find next function declaration.")
   nil))))
 "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.")

(custom-set-variables
 '(doxymacs-file-comment-template doxymacs-my-file-comment-template)
 '(doxymacs-function-comment-template
   doxymacs-my-function-comment-template)
 '(doxymacs-blank-multiline-comment-template
   doxymacs-my-blank-multiline-comment-template)
 '(doxymacs-blank-singleline-comment-template
   doxymacs-my-blank-singleline-comment-template)
)