costumizing commenting style

[Miles]

Hi,

Doxymacs works pretty well, but there is a thing I would like to know:

Is there a way to costumize how doxymacs builds the comments. To be more specific, I would like to use the QT Style in general (that was easy to achieve). So everytime I use C-c d f to get the comment, I get something like this:
//!
/*!

\param id
*/

Well, that's ok, it works, but I would like to get rid of the first //! and prepend each line with an asterisk and spaces to make it look more like this (I substituted the spaces with underscores, to prevent browsers mangling them):

/*!
_*___
_*___\param id
_*/

Is there an option where I can costumize this? I didn't find anything.

I know that's not an essential question, but I would be gratefull if anybody could help me with this. If it's not possible or not that easy, I would be gratefull for that info too, so I would stop bothering around ;-)

Miles

[Georg]

Hello Miles,

you can customise the comment style by redefining some templates.  Doxymacs uses tempo
templates (http://www.lysator.liu.se/~davidk/elisp/) to generate the
comments.  You can overwrite the default templates defined in
doxymacs.el with your own customised templates.

The default template used for function comments (Qt style) looks like
this:

(defconst doxymacs-Qt-function-comment-template
'((let ((next-func (doxymacs-find-next-func)))
     (if next-func
     (list
      'l
      "//! " 'p '> 'n
      "/*! " '> 'n
      " " '> 'n
      (doxymacs-parm-tempo-element (cdr (assoc 'args next-func)))
      (unless (string-match
                   (regexp-quote (cdr (assoc 'return next-func)))
                   doxymacs-void-types)
        '(l " " > n "  \\return " (p "Returns: ") > n))
      " */" '>)
       (progn
     (error "Can't find next function declaraton.")
     nil))))
"Default Qt-style template for function documentation.")

You can use your own template with your requested formate if you
define the following helper function and the new template
doxymacs-function-comment-template which overrides the build-in one:

(defun doxymacs-parm-user-tempo-element (parms)
  "Inserts tempo elements for the given parms in the given style."
  (if parms
      (let ((prompt (concat "Parameter " (car parms) ": ")))
        (list 'l " *   @param " (car parms) " " (list 'p prompt) '> 'n
              (doxymacs-parm-user-tempo-element (cdr parms))))
    nil)
)

(setq doxymacs-function-comment-template
      '((let ((next-func (doxymacs-find-next-func)))
          (if next-func
              ;; return tempo macro list
              (list
               'l
               "/*!  @brief " '(p "Brief description of this function: ") '> 'n
               (doxymacs-parm-user-tempo-element (cdr (assoc 'args next-func)))
               (unless (string-match
                        (regexp-quote (cdr (assoc 'return next-func)))
                        doxymacs-void-types)
                 '(l " *   @return " (p "Returns: ") > n
                     " *   @retval <value> <description>" > n))
               " * "  'p '> 'n
               " */" '>)
            ;; else issue the error and return nil
            (error "Can't find next function declaration.")
            nil)))
)

You can include the latter source code part in your .emacs file after
the point where you activate doxymacs with "(require 'doxymacs)".

Writing new tempo templates is not trivial.  You may have a look at
the tempo documentation and the doxymacs source code doxymacs.el to
learn more about their use.

Regards
Georg

[Miles]

Hello Georg,

thanks, that did it. Now it's just what I was looking for.

I altered it a little, although it stills looks a bit cryptic to me ;-)

thanks,

Miles