Doxygen-style comments in vim for C++

Question

I'd like to automate inserting comment snippets for C++ files. Google search suggested c.vim plugin. I installed it. Now when I create a file, I get template like following.

 /* =====================================================================================
  *
  *       Filename:  Foo.h
  *
  *    Description:  :
  *
  *        Version:  1.0
  *        Created:  04/14/2014 08:35:44 PM
  *       Revision:  none
  *       Compiler:  gcc
  *
  *         Author:  YOUR NAME (), 
  *   Organization:  
  *
  * =====================================================================================
  */

From :h csupport I catch I can create my own templates for comments. Is there simpler way to get doxygen-style comments in project? Or maybe these templates are available somewhere?

Answer 1

If you only need these comments and not the other features of c.vim, I'd recommend you to use some snippets plugin, such as Snipmate or Ultisnips. Creating such snippets with these plugins is very easy and they are very powerful.

Answer 2

You can use Doxygen plugin for vim. It's available here. Simply enter :Dox to add your comments.

For example,

/**
 * @brief 
 *  
 * @param list 
 * @param size
 * @param key
 * @param rec
 *
 * @return 
 */
bool jw_search ( int *list, int size, int key, int& rec )
{
    return true;
}

Answer 3

lh-cpp & mu-template come with tunable project headers (the default is quite bad I have to admit). You'll have to override templates/c/internals/c-file-header.template to something like:

VimL: let s:filename = s:path_from_root(expand('%:p'))
VimL: let s:prj_dox_group = lh#option#get('my_prj_dox_group', lh#marker#txt('group'))
/**@file <+s:filename+>
 * @ingroup <+s:prj_dox_group+>
 * @author  <+Author()+>
 * <p>Licence:<p> Your Project Licence
 */

(All the other stuff is already taken care of: include guards will be added automatically in header files, and foo.h will be automatically included in foo.c(pp))

Then in a local_vimrc-like plugin, you'll have to set:

" File: /root/path/of/the/project/_vimrc_local.vim
:let b:my_prj_dox_group = "gMain" " you can override it in subfolders
:let b:sources_root = '/root/path/of/the/project' " for mu-template
:let b:includes = [b:sources_root . '/**'] " I can't remember which ftplugin uses b:includes
:let b:included_paths = [b:sources_root] " for ftplugin/c/c_AddInclude.vim
:let g:alternateSearchPath = 'sfr:.' " (or equivalent) for a.vim and for foo.cpp to include foo.h

BTW, lh-cpp also comes with the :DOX command that'll parse a function signature to automatically generate its doxygen caption (@param[in/out/0], @return, @ingroup, @throw (noexcept and the deprecated exception specifications are analysed), ... will be filled as automagically as possible)

If we take Saraht's example, it becomes:

/**
 * «brief explanation».
 * «details»
 * @param[«in,»out] list  «list-explanations»
 * @param[in] size  «size-explanations»
 * @param[in] key  «key-explanations»
 * @param[«in,»out] rec  «rec-explanations»
 *
 * @return «bool»
 * «@throw »
 * @pre <tt>list != NULL</tt>«»
 */
bool jw_search ( int* list, int size, int key, int& rec )

NB: «» occurrences mark placeholders

PS: I have no idea how it will behave if your keep c.vim as I don't use it.