In fact, most developers around the world probably dislike writing comments within their programs, no matter which language is considered. However, exhaustive code documentation improves the overall code quality, and thus also the software quality. Moreover, code documentation is essential in projects where teams with several people work on the same code base. Thus, the motivation to simplify the writing of comments/code documentation is very high, because the developer wants to focus on the essentials, namely the semantic and contents of the documentation and not any kind of syntax (/* ... */). Since the eclipse IDE has an inherent high comfort concerning auto-completion of javadoc and doxygen comments, I was a bit disappointed when I switched to emacs, because there is no such thing in emacs by default. Fortunately, there’s an emacs extension called Doxymacs, which can be obtained from this link.
Installation
If you are using ubuntu, then you’re lucky, since ubuntu has a dedicated package called doxymacs
Configuration and Usage
After successful installation, you should modify your ~/.emacs file to include doxymacs:
1
2
3
4
5
6
| (require 'doxymacs)
(add-hook 'c-mode-common-hook 'doxymacs-mode)
(defun my-doxymacs-font-lock-hook ()
(if (or (eq major-mode 'c-mode) (eq major-mode 'c++-mode))
(doxymacs-font-lock)))
(add-hook 'font-lock-mode-hook 'my-doxymacs-font-lock-hook) |
where the second line automatically activates doxymacs for the c-mode, which is most likely what you want. Furthermore, the function and its invocation in lines 3-6 enables pretty fontification for doxygen keywords (e.g. param)
The defaults key-bindings are as follows:
C-c d ? will look up documentation for the symbol under the point.C-c d r will rescan your Doxygen tags file.C-c d f will insert a Doxygen comment for the next function.C-c d i will insert a Doxygen comment for the current file.C-c d ; will insert a Doxygen comment for a member variable on the current line (like M-;).C-c d m will insert a blank multi-line Doxygen comment.C-c d s will insert a blank single-line Doxygen comment.C-c d @ will insert grouping comments around the current region.
Additions
I found the following function that automatically inserts an asterisk (*) whenever one is hitting return within a multiline comment:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
| (defun my-javadoc-return ()
"Advanced C-m for Javadoc multiline comments.
Inserts `*' at the beggining of the new line if
unless return was pressed outside the comment"
(interactive)
(setq last (point))
(setq is-inside
(if (search-backward "*/" nil t)
;; there are some comment endings - search forward
(if (search-forward "/*" last t)
't
'nil)
;; it's the only comment - search backward
(goto-char last)
(if (search-backward "/*" nil t)
't
'nil
)
)
)
;; go to last char position
(goto-char last)
;; the point is inside some comment, insert `*'
(if is-inside
(progn
(insert "\n*")
(indent-for-tab-command))
;; else insert only new-line
(insert "\n")))
(add-hook 'c++-mode-hook (lambda ()
(local-set-key "\r" 'my-javadoc-return))) |
Links
