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, [e-mail]"
       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