Emacs C-mode indent problem with Doxygen style comment

Question

I am having a problem with Doxygen style multi-line comments with emacs indent feature in c-mode. According to Doxygen manual (http://www.stack.nl/~dimitri/doxygen/docblocks.html) the form below is accepted.

 /********************************************//**
 *  ... text
 ***********************************************/

I am trying to use this format in emacs but when I tab in on the line '* ... text' the * ends up below the /** at the end of the first line like so:

 /********************************************//**
                                                *  ... text
 ***********************************************/

Any suggestions on how to fix this? Still learning all the in-and-outs of emacs.

Thanks.

Answer 1

this very strange, i generate comments with doxymacs and this handled by cc-mode correctly

Answer 2

Which version of emacs are you using? My emacs 22 has this problem, but on another machine with emacs 23 does not. This is probalby due to some "electric" indentation. Try M-x describe-key RET RET and also M-x describe-mode to get a nice place to start searching for clues. There is also http://doxymacs.sourceforge.net/ but I have not tesed it personally.

Answer 3

The reason it is indenting as such is that (by default) multi-line comments are lined up with the start of the comment on the previous line. In this case, the start of the containing comment is in column 47.

Now, how to fix it. Here's how I figured out how to fix it, the solution is at the end.

First, there's the cc-mode manual, specifically the section on customizing indentation. A useful key is C-c C-s which tells you which syntax is being used for indentation. In this case it is ((c 61)) - the c is the important part for now.

To customize it interactively, you can type C-c C-o (when the point is on the line whose indentation you want to fix). You'll be prompted for which syntax entry you want to customize (defaults to c in this case b/c that's the current syntax), then you'll be prompted for what you want to change the syntax entry to (default is c-lineup-C-comments).

Now we can look at that function to see how we might customize it to meet your needs. M-x find-function c-lineup-C-comments.

That's where it gets more difficult. You can customize the way cc-mode handles comment indentation, but what it looks like you want it to do (in this case) is to recognize that the c-comment you're in is immediately preceded by another c-comment, and that comment is the one you want to align indentation to.

How do you do that? The easiest way I can think of is to advise 'c-lineup-C-comments to recognize this special case and change the value of its first argument to be what you want. My limited testing shows this works for your example:

(defadvice c-lineup-C-comments (before c-lineup-C-comments-handle-doxygen activate)
  (let ((langelm (ad-get-arg 0)))
    (save-excursion
      (save-match-data 
        (goto-char (1+ (c-langelem-pos langelem)))
        (if (progn
              (beginning-of-line)
              ;; only when the langelm is of form (c . something)
              ;; and we're at a doxygen comment line
              (and (eq 'c (car langelm))
                   (looking-at "^\\(\\s-*\\)/\\*+//\\*\\*$")))
            ;; set the goal position to what we want
            (ad-set-arg 0 (cons 'c (match-end 1))))))))

The end result of this advice should be that the argument passed into c-lineup-C-comments should be transformed from (c . 61) to (c . 17) (or something like that), essentially fooling the routine into lining up with the comment at the beginning of the line, and not the comment which you're currently modifying.