How to collapse (fold) Doxygen comments by default in vim?

4
votes

We're looking at adding Doxygen documentation to C++ header files, but some people would prefer not to see the verbose Doxygen documentation by default.

Is there a way in .vimrc to fold (collapse) Doxygen comments by default?

Note: I have tried autocmd FileType c,cpp set foldmethod=syntax which will collapse all matching syntax, but I have been unable to figure out how to avoid collapsing functions, classes, et al., i.e. to only collapse Doxygen documentation format.

Another solution that looks like it might be a good one if the C-fold plugin for vim. Here's a detailed install sequence to get it working:

  1. Add Doxygen syntax highlighting

(a) Install it from http://vim.sourceforge.net/scripts/script.php?script_id=5 which will create ~/.vim/syntax/doxygen.vim.

(b) Add ~/.vim\ftdetect\doxygen.vim with this single line:

au BufNewFile,BufRead *.doxygen setfiletype doxygen

(c) Add ~/.vim/syntax/doxygen_load.vim with these two lines:

au! Syntax {cpp,c,idl}
au Syntax {cpp,c,idl} runtime syntax/doxygen.vim

  1. Add at the end of ~/.vimrc:

    let mysyntaxfile='/home/dchinner/.vim/syntax/doxygen_load.vim' autocmd FileType c,cpp set foldmethod=syntax autocmd FileType c,cpp set foldlevel=10

Note that foldlevel determines how much will be folded initially. A high value will ensure most is open.

  1. Add C-fold to (un)fold code or comments

(a) Install it from http://vim.sourceforge.net/scripts/script.php?script_id=1145 which will install ~/.vim/plugins/cfold.vim and ~/.vim/after/syntax/c.vim.

(b) Add at the end of ~/.vim/syntax/doxygen.vim:

syn region doxygenComment start= ... keepend fold

Done! You can now use these C-fold plugin key-combos:

  • z[ opens all doxygen-style comments
  • z] closes all doxygen-style comments
  • z{ opens all code blocks
  • z} closes all code blocks

vim a file with Doxygen comments, and hit z] to fold the Doxygen comments.

1
c++vim

1 Answers

2
votes

Both syntax/c.vim and syntax/doxygen.vim use syntax folding. Since there is no condition around the fold definitions in c.vim, you cannot turn off just one part.

You have to fork the default $VIMRUNTIME/syntax/c.vim into ~/.vim/syntax/c.vim, and remove all fold attributes from the syntax commands. That should leave just the doxygen parts folded (with :set foldmethod=syntax). The downside is that you have to maintain your special version of c.vim from now on.