DoxygenToolKit.vim 插件配置

如何才能既享受 Doxygen 的强大功能，同时又避免大量的重复性的注释内容？

解决思路： 让编辑器来替咱们写那些格式和内容固定的部分，咱们只负责写真正的有效内容。

因此，答案就是：Vim + DoxygenToolKit.vim 插件

DoxygenToolKit

---

DoxygenToolKit 是 Vim 的一款插件，用它能够很方便地添加 Doxygen 风格的注释，能够节省大量时间和精力，提升写代码的效率。

DoxygenToolKit Official Website 官网上介绍，目前定义了 5 个功能：

• Generates a doxygen license comment. The tag text is configurable.

• Generates a doxygen author skeleton. The tag text is configurable.

• Generates a doxygen comment skeleton for a C, C++ or Python function or class, including @brief, @param (for each named argument), and @return. The tag text as well as a comment block header and footer are configurable. (Consequently, you can have \brief, etc. if you wish, with little effort.)

• Ignore code fragment placed in a block defined by #ifdef ... #endif (C/C++). The block name must be given to the function. All of the corresponding blocks in all the file will be treated and placed in a new block DOX_SKIP_BLOCK (or any other name that you have configured). Then you have to update PREDEFINED value in your doxygen configuration file with correct block name. You also have to set ENABLE_PREPROCESSING to YES.

• Generate a doxygen group (begining and ending). The tag text is configurable.

Installation

若是咱们使用 Vundle 管理插件，安装步骤就很是简单了：

1. 在 Vundle 中加入：

   Bundle 'DoxygenToolkit.vim'
   

2. 打开 Vim，输入命令：

   :BundleInstall
   

Vundle 会自动完成安装 :-D

Configuration for c++

咱们有两种方法能够修改设置，方法一是直接在 DoxygenToolKit.vim 脚本文件中修改相关变量；方法二是在 ~/.vimrc 里面修改。显然方法二更加好一点，由于若是用方法一直接改原脚本，可能还得保存备份才能恢复默认值。

由于平时写的 C++ 程序比较多，因此针对基于 Doxygen 的 C++ 注释风格，咱们须要进行如下几步：

1. 在 .vimrc 中我特别配置了如下命令：

       let g:DoxygenToolkit_briefTag_funcName = "yes"
   
       " for C++ style, change the '@' to '\'
       let g:DoxygenToolkit_commentType = "C++"
       let g:DoxygenToolkit_briefTag_pre = "\\brief "
       let g:DoxygenToolkit_templateParamTag_pre = "\\tparam "
       let g:DoxygenToolkit_paramTag_pre = "\\param "
       let g:DoxygenToolkit_returnTag = "\\return "
       let g:DoxygenToolkit_throwTag_pre = "\\throw " " @exception is also valid
       let g:DoxygenToolkit_fileTag = "\\file "
       let g:DoxygenToolkit_dateTag = "\\date "
       let g:DoxygenToolkit_authorTag = "\\author "
       let g:DoxygenToolkit_versionTag = "\\version "
       let g:DoxygenToolkit_blockTag = "\\name "
       let g:DoxygenToolkit_classTag = "\\class "
       let g:DoxygenToolkit_authorName = "Qian Gu, guqian110@gmail.com"
       let g:doxygen_enhanced_color = 1
       "let g:load_doxygen_syntax = 1
   

2. 即便前一步中设置了 C++ 风格，可是生成的 Lisence 仍然是 //，而不是咱们想要的 ///，因此咱们还须要修改原脚本（line 362~363）为：

   let g:DoxygenToolKit_startCommentBlock = "/// "
   let g:DoxygenToolKit_interCommentBlock = "/// "
   

Usage

官网上也给出了使用方法：

• License

  将光标放在须要生成 License 的地方，而后输入命令 :DoxLic

• Author

  将光标放在合适的地方，而后输入命令 :DoxAuthor

• Function / Class

  将光标放在 function 或者 class 的名字所在的一行，而后输入命令 :Dox

• Ignore code fragment (C/C++ Only)

  若是想忽略调试部分的代码，那么只须要执行命令 :DoxUndoc(DEBUG) 便可

• Group

  输入命令 DoxBlock 来插入一个注释块

为了方便使用，咱们能够自定义一些 map，省去输入命令的繁琐。

Example

一样是官网上的例子：

假设有个函数以下

1 2 3 4 5 6 7

int foo(char mychar, int myint, double* myarray, int mask = DEFAULT) { //... }

那么执行 :Dox 命令以后会生成如下内容

1 2 3 4 5 6 7 8 9 10

/** * @brief * * @param mychar * @param myint * @param myarray * @param mask * * @return */

Ref

DoxygenToolKit.vim