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