sponsor Vim development Vim logo Vim Book Ad

DoxygenToolkit.vim : Simplify Doxygen documentation in C, C++, Python.

 script karma  Rating 462/220, Downloaded by 18543    Comments, bugs, improvements  Vim wiki

created by
Mathias Lorente
 
script type
utility
 
description
Currently five purposes have been defined :

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.

Use:
- Type of comments (C/C++: /// or /** ... */, Python: ## and # ) :
  In vim, default C++ comments are : /** ... */. But if you prefer to use ///
  Doxygen comments just add 'let g:DoxygenToolkit_commentType = "C++"'
  (without quotes) in your .vimrc file

- License :
  In vim, place the cursor on the line that will follow doxygen license
  comment.  Then, execute the command :DoxLic.  This will generate license
  comment and leave the cursor on the line just after.

- Author :
  In vim, place the cursor on the line that will follow doxygen author
  comment.  Then, execute the command :DoxAuthor.  This will generate the
  skeleton and leave the cursor just after @author tag if no variable
  define it, or just after the skeleton.

- Function / class comment :
  In vim, place the cursor on the line of the function header (or returned
  value of the function) or the class.  Then execute the command :Dox.  This
  will generate the skeleton and leave the cursor after the @brief tag.

- Ignore code fragment (C/C++ only) :
  In vim, if you want to ignore all code fragment placed in a block such as :
    #ifdef DEBUG
    ...
    #endif
  You only have to execute the command :DoxUndoc(DEBUG) !
  
- Group :
  In vim, execute the command :DoxBlock to insert a doxygen block on the
  following line.

Limitations:
- Assumes that the function name (and the following opening parenthesis) is
  at least on the third line after current cursor position.
- Not able to update a comment block after it's been written.
- Blocks delimiters (header and footer) are only included for function
  comment.
- Assumes that cindent is used.
- Comments in function parameters (such as void foo(int bar /* ... */, baz))
  are not yet supported.


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

Issuing the :Dox command with the cursor on the function declaration would
generate

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


To customize the output of the script, see the g:DoxygenToolkit_*
variables in the script's source.  These variables can be set in your
.vimrc.

For example, my .vimrc contains:
let g:DoxygenToolkit_briefTag_pre="@Synopsis  "
let g:DoxygenToolkit_paramTag_pre="@Param "
let g:DoxygenToolkit_returnTag="@Returns   "
let g:DoxygenToolkit_blockHeader="--------------------------------------------------------------------------"
let g:DoxygenToolkit_blockFooter="----------------------------------------------------------------------------"
let g:DoxygenToolkit_authorName="Mathias Lorente"
let g:DoxygenToolkit_licenseTag="My own license"   <-- !!! Does not end with "\<enter>"
 
install details
Copy to your '~/.vim/plugin' directory
 

rate this script Life Changing Helpful Unfulfilling 
script versions (upload new version)

Click on the package to download.

package script version date Vim version user release notes
DoxygenToolkit.vim 0.2.13 2010-10-16 7.0 Mathias Lorente Correct insertion position and 'xxx_post' parameters.
   - Insert position is correct when g:DoxygenToolkit_compactOneLineDoc = "yes" and let g:DoxygenToolkit_commentType = "C++" are set.
   - When you define:
        g:DoxygenToolkit_briefTag_pre = "@brief "
        g:DoxygenToolkit_briefTag_post = "<++>"
        g:DoxygenToolkit_briefTag_funcName = "yes"
     Documentation generated with these parameters is something like:
        /// @brief foo <++>
     You can configure similarly parameters to get something like:
        /// @brief foo <++>
        /// @param bar <++>
        /// @param baz <++>
DoxygenToolkit.vim 0.2.12 2010-09-09 7.0 Mathias Lorente Position the cursor at the right position for one line documentation.
(thanks to brian kropf)
DoxygenToolkit.vim 0.2.11 2010-08-25 7.0 Mathias Lorente Remove trailing blank characters where they are not needed. (Thanks to Lukas Grässlin)
DoxygenToolkit.vim 0.2.10 2010-08-08 7.0 Mathias Lorente 'extern' keyword added in list of values to ignore for return type.
DoxygenToolkit.vim 0.2.9 2010-08-08 7.0 Mathias Lorente Correct bugs related to templates and add support for throw statement (many thanks to Dennis Lubert):
- Template parameter of different type from class and typename are recognized.
- Indentation mistake while detecting template.
- New options are available: g:DoxygenToolkit_throwTag_pre (default set to '@throw ', can be changed to '@exception ' and g:DoxygenToolkit_throwTag_post
DoxygenToolkit.vim 0.2.8 2010-08-06 7.0 Mathias Lorente Add support for documentation of template parameters.
(Thanks to Dennis)
DoxygenToolkit.vim 0.2.7 2009-12-06 7.0 Mathias Lorente Increase comparibility with c/c++ IDE
DoxygenToolkit.vim 0.2.6 2009-11-19 7.0 Mathias Lorente Bug correction (thanks to Jhon Do):
DoxygenToolkit_briefTag_funcName and other xxx_xxName parameters should work properly now.
DoxygenToolkit.vim 0.2.5 2009-08-21 7.0 Mathias Lorente DoxLic function is corrected (thanks to Roland Kammerer). Date and name are properly set.
DoxygenToolkit.vim 0.2.4 2009-05-11 7.0 Mathias Lorente Bug correction (thanks to Anders Bo Rasmussen)
   - C++: now functions like  void foo(type &bar); are correctly documented.
          The parameter's name is 'bar' (and no more '&bar').
DoxygenToolkit.vim 0.2.3 2009-03-26 7.0 Mathias Lorente Added @version tag into the DocBlock generated by DoxygenAuthorFunc() (thanks to Dave Walter).
DoxygenToolkit.vim 0.2.2 2009-01-20 7.0 Mathias Lorente Comments are now allowed in function declaration. Example:
- C/C++:   void func( int foo, // first param
                                   int bar  /* second param */);

- Python:  def func( foo,  # first param
                                 bar ) # second param
DoxygenToolkit.vim 0.2.1 2009-01-15 7.0 Mathias Lorente Bug correction (many thanks to Alexey Radkov)
- C/C++: following function/method are now correctly documented:
   - operator(),
   - constructor with initialization parameter(s),
   - pure virtual method,
   - const method.

- Python:
   - Single line function are now correctly documented.
DoxygenToolkit.vim 0.2.0 2009-01-13 7.0 Mathias Lorente The main function has been rewritten (I hope it is cleaner).
- There is now support for function pointer as parameter (C/C++).
- You can configure the script to get one line documentation (for
   attribute instance for example, you need to set
   g:DoxygenToolkit_compactOneLineDoc to "yes").

- NEW: Support Python scripts:
   - Function/method are not scanned, so by default they are considered
      as if they always return something (modify this behavior by defining
      g:DoxygenToolkit_python_autoFunctionReturn to "no")
   - self parameter is automatically ignored when scanning function
      parameters (you can change this behavior by defining
      g:DoxygenToolkit_python_autoRemoveSelfParam to "no")
DoxygenToolkit.vim 0.1.17 2007-04-15 6.0 Mathias Lorente Number of lines scanned is now configurable. Default value is still 10 lines. (Thanks to Spencer Collyer for this improvement).
DoxygenToolkit.vim 0.1.16 2007-02-27 6.0 Mathias Lorente Bug correction : now, function that returns null pointer are correctly documented (thanks to Ronald WAHL for his report and patch).
DoxygenToolkit.vim 0.1.15 2007-02-11 6.0 Mathias Lorente Generated documentation with block header/footer activated do not integrate header and footer anymore.
DoxygenToolkit.vim 0.1.14 2006-11-04 6.0 Mathias Lorente New option available for cinoptions : g:DoxygenToolkit_cinoptions (default value is still c1C1)
Thanks to Arnaud GODET for this. Now comment can have different indentation style.
DoxygenToolkit.vim 0.1.13 2005-04-17 6.0 Mathias Lorente Changes for linux kernel comment style
DoxygenToolkit.vim 0.1.12 2005-03-21 6.0 Mathias Lorente Fixed indentation in comments (suggested by Soh Kok Hong and required by other users)
DoxygenToolkit.vim 0.1.12 2005-01-27 6.0 Mathias Lorente Now you can use your own comment tag (not only C or C++). In this case, you have to define: 'g:DoxygenToolkit_startCommentTag', 'g:DoxygenToolkit_interCommentTag' and 'g:DoxygenToolkit_endCommentTag' in your .vimrc file.
DoxygenToolkit.vim 0.1.11 2004-11-22 6.0 Mathias Lorente The real 0.1.11 version...
Sorry for my mistake (thank to Jason Mills who pointed me out this error....)
DoxygenToolkit.vim 0.1.10 2004-06-01 6.0 Mathias Lorente Bug correction for constructors / destructor and functions preceded by spaces (or tabs).
DoxygenToolkit.vim 0.1.9 2004-05-25 6.0 Mathias Lorente Fixed filename bug when including doxygen author comment whereas file has not been open directly on commamd line.
Now /// or /** doxygen comments are correctly integrated (except for license).
DoxygenToolkit.vim 0.1.8 2004-05-24 6.0 Mathias Lorente Some changes and bug correction for some configuration (thanks to Jason Mills).
DoxygenToolkit.vim 0.1.7 2004-05-17 6.0 Mathias Lorente Bug correction in DoxygenUndocumentFunc.
DoxygenToolkit.vim 0.1.6 2004-05-14 6.0 Mathias Lorente Few code modification and new functionalities
DoxygenToolkit.vim 0.1.5 2004-05-14 6.0 Mathias Lorente Initial upload
ip used for rating: 54.80.121.186

If you have questions or remarks about this site, visit the vimonline development pages. Please use this site responsibly.
Questions about Vim should go to the maillist. Help Bram help Uganda.
   
SourceForge.net Logo