Emacs - Doxygen

Table of Contents

Introduction

Doxygen1 is a powerful tool to document the source codes. In principle, it parses the specially formated comments from the source codes and then produces very professional documents. Up to now, it is able to support almost all the popular programming languages, e.g. C/C++, Java, Python, and etc.

Syntax

Comment block

Multi-line comment blocks
Begin with /** or /*!, and end with */.
Single-line comment blocks
delimiters /// or //!.

Special command

Within code blocks, special commands can be used. They begin with a prefix @ or \ and optionally have arguments enclosed in braces. Moreover, different braces mean different scopes.

  • Angle braces < > mean the argument is a single word.
  • Round braces ( ) mean the argument extends to end of line.
  • Curly braces { } mean the argument extends to next paragraph.

List

  • Column aligned - → a unsorted/bulleted list item.
  • Column aligned -# → a sorted list item.

Hierachical lists can be created by using different indents for different levels.

Group

/** \defgroup <label> ''<title>'' */
/* @{ */
   // group memebers here ...
/* @} */

or 

/** \defgroup <label> ''<title>'' */
// @{
   // group memebers here ...
// @}

where the title is optional while the label is mandatory and can be used for reference by 

\ref <label> ''<link>''

Formula

  • Inline formula
\f$ ... \f$
  • Centered formula
\f[ ... \f]

Graph

Doxygen can automatically generate graphs by dot from Graphviz2. Additionally, mannual dot commands are enclosed between \dot and \enddot.

Text

  • \a/\e <word>: word
  • \b <word>: word
  • \c <word>: word

Section

  • \attention {...}: an Attention paragraph
  • \author {...}: author list
  • \brief {...}: a brief description
  • \bug {...}: a bug description
  • \date {...}
  • \deprecated {...}: a Deprecated paragraph
  • \note {...}: a Note paragraph
  • \par (title) {...}: a paragraph with a optional title
  • \param <p> {...}: a description of parameter p
  • \return {...}: a description of return values
  • \remarks {...}: a Remarks paragraph
  • \sa/\see {ref}: a See Also paragraph
  • \todo {...}: a To Do paragraph
  • \version {...}: a paragraph including the version string
  • \warning {...}: a paragraph for warning messages

Doxymacs

There is a doxygen extension for Emacs, doxymacs, which provides a minor mode for doxygen doxymacs-mode. Clearly, it stands for doxygen + emacs. With it, comment blocks above can be conveniently inserted.

Installation

  • For ArchLinux, doxymacs can be easily installed by AUR. 

    yaourt doxymacs

  • From source codes, the installation can be completed by following procedure. 

    # Download the codes to local, e.g., elpa.
cd ~/.config/emacs/elpa
git clone --depth=1 https://github.com/pniedzielski/doxymacs

# Install it to, e.g., elpa.
cd doxymacs
./bootstrap
./configure --prefix=~/.config/emacs/elpa/doxymacs
make
make install

Configuration

After the installation, following configuration should be inserted into Emacs configuration file .emacs. 

(use-package doxymacs
  :ensure nil
  :load-path "elpa/doxymacs/lisp"
  :hook ((c-ts-mode-hook c++-ts-mode-hook) doxymacs-mode)
  :commands doxymacs-mode)

Usage

Doxymacs-mode provides following key bindings.

Key Binding
C-c d ; doxymacs-insert-member-comment
C-c d ? doxymacs-lookup
C-c d @ doxymacs-insert-grouping-comments
C-c d f doxymacs-insert-function-comment
C-c d i doxymacs-insert-file-comment
C-c d m doxymacs-insert-blank-multiline-comment
C-c d r doxymacs-rescan-tags
C-c d s doxymacs-insert-blank-singleline-comment

Footnotes:

1

http://www.doxygen.nl

2

http://www.graphviz.org