costumizing commenting style

  • Miles

    Miles - 2004-09-13


    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 ;-)


    • Georg

      Georg - 2004-09-16

      Hello Miles,

      you can customise the comment style by redefining some templates.  Doxymacs uses tempo
      templates ( 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

      (defconst doxymacs-Qt-function-comment-template
      '((let ((next-func (doxymacs-find-next-func)))
           (if next-func
            "//! " 'p '> 'n
            "/*! " '> 'n
            " " '> 'n
            (doxymacs-parm-tempo-element (cdr (assoc 'args next-func)))
            (unless (string-match
                         (regexp-quote (cdr (assoc 'return next-func)))
              '(l " " > n "  \\return " (p "Returns: ") > n))
            " */" '>)
           (error "Can't find next function declaraton.")
      "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))))

      (setq doxymacs-function-comment-template
            '((let ((next-func (doxymacs-find-next-func)))
                (if next-func
                    ;; return tempo macro list
                     "/*!  @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)))
                       '(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.")

      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.


    • Miles

      Miles - 2004-09-16

      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 ;-)




Log in to post a comment.