Visual Studio .NET的Doxygen 外掛程式 – KingTools.

文章目錄

• Run Doxygen
• Insert Doxygen comments
• Build Solution stats
• Dependency and Inheritance graph
• Swap .h<->.cpp
• Colorize
• } End of
• #region/#endregion for C++
• Search the web

 

Visual Studio .NET的Doxygen 外掛程式 - KingTools：

http://www.codeproject.com/macro/KingsTools.asp

• Download Installer - 1847 Kb
• Download source - 47 Kb

Introduction

As good as Visual Studio .NET is, I still miss some features in it. But MS knew that they couldn't fulfill every wish so they provided a way to write addins. That's what I've done. Sure, most of the functions in my Tools could also be done with macros, but I wanted them all packed together with an installer.

Tools

• Run Doxygen
• Insert Doxygen comments
• Build Solution stats
• Dependency Graph
• Inheritance Graph
• Swap .h<->.cpp
• Colorize
• } End of
• #region/#endregion for c++
• Search the web

Run Doxygen

This command first pops up a dialog box in which you can configure the output Doxygen should produce. For those who don't know Doxygen: it's a free tool to generate source documentations. It can produce documentation in different formats like html and even windows help format! See http://www.doxygen.org/ for details. Since the dialog box doesn't offer all possible settings for doxygen, you can always edit the file Doxyfile.cfg manually which is created the first time you run it. All settings in that file override the settings you enter in the dialog box.

If you set Doxygen to generate html output, the resulting index.html is opened inside the IDE. A winhelp output (index.chm) will be opened outside the IDE.

The command available from the Tools menu builds the documentation for the whole solution. If you don't want that for example if you have several third party projects in your solution then you can build the documentation also for single projects. To do that the KingsTools add a command to the right click menu in the solution explorer.

If you want to update Doxygen to a newer version (as soon as one is released) simply overwrite the doxygen.exe in the installation directory. The same applies to the dot.exe.

TODO: find a way to integrate the generated windows help file into VS help.

Insert Doxygen comments

Doxygen needs comments that follow certain conventions to build documentation from. This part of the tools inserts them for you. Either from the right click menu in the code editor window or from the submenu under Tools->Kings Tools. Just place the caret over a method or class header. The inserted comment for a method or function would look like this:

/** * * /param one * /param two * /param three * /return */BOOL myfunction(int one, int two, int three);

You now have to simply insert a description in the second comment line and descriptions for each parameter of the function/method. And of course a description of the return value.

You can customize the function comments by editing the files "functionheadertop.txt", "functionparams.txt" and "functionheaderbottom.txt". Please read the comments inside those files on how to do that. If you don't want to change the function comments for all your projects then you can place any of those files into your project directory (that way it will be used for your project) or inside the folder of your source files (that way it will be used only for the files inside that specific folder).

The inserted comment for a class looks like this:

/** * /ingroup projectname * * /par requirements * win98 or later, win2k or later, win95 with IE4 or later, winNT4 with IE4  * or later * * /author user * * /par license * This code is absolutely free to use and modify. The code is provided  * "as is" with no expressed or implied warranty. The author accepts no  * liability if it causes any damage to your computer, causes your pet to  * fall ill, increases baldness or makes your car start emitting strange  * noises when you start it up. This code has no bugs, just undocumented  * features! * * /version 1.0 * /date 06-2002 * /todo * /bug * /warning * */class CRegBase

The '/ingroup projectname' means that the class is inside the project 'projectname'. That statement helps Doxygen to group classes together. Insert the description of the class right after that statement. If you want to include pictures to illustrate the class, use '/image html "picture.jpg"'. For more helpful tags you can use please check out the Doxygen website. The '/par requirements' section you have to modify yourself to fit the truth of your class. It's not necessary for Doxygen, but I found it very useful to give that information inside a class documentation. The name after the '/author' tag is the currently logged in user. Maybe you want to change that too to include an email address.

You can customize the class comments by editing the file "classheader.txt" Please read the comments inside that file on how to do that. If you don't want to change the class comments for all your projects then you can place that files into your project directory (that way it will be used for your project) or inside the folder of your source files (that way it will be used only for the files inside that specific folder).

The last few tags should be self-explanatory. Under the line '/version' I usually insert short descriptions of what changed between versions.

Build Solution stats

This is a simple line counter. It counts all the lines of all files in your solution, grouped by projects. The generated html file with the counted lines (code, comments, empty) is then opened in the IDE. Since I haven't found a way to add a file directly to a solution and not to a project the file is just opened for view in the IDE.

Dependency and Inheritance graph

These two commands build graphs of the class relations in your solution. See my previous article about this. The difference to my old tool is that it now generates graphs for all projects in the solution and puts all the graphs in one single html page.

Swap .h<->.cpp

This is something a simple macro could also do: it swaps between header and code files. For better accessibility it also is on the right click menu of the code editor. Really nothing special but it can be useful sometimes.

Colorize

This tool goes through all files of the current solution and looks for class, function and macronames. It then writes them to a usertype.dat file, makes the IDE to read that file and deletes it again. After you run this tool, all class, function and macronames of your solution appear colored in the code editor. Default color is the same color as normal keywords, but you can change that under Tools->Options, in the Options dialog select Environment->Fonts and Colors.

If you don't want the colors anymore, just run the command 'disable coloring' and everything will be in normal colors again. I didn't want to overwrite some possible usertype.dat file already created by some user so the tool simply creates a temporary usertype.dat file instead. If you want to have the colors again the next time the IDE starts, you either have to rerun the command (doesn't take very long to execute) or change the code of the tool yourself.

} End of

Have you ever wrote a bunch of code which looked like this:

Ok, I admit this isn't a very good style of programming, but sometimes it can't be avoided. And in those cases the code is horrible to read because you don't know which closing brace belongs to which opening statement without scrolling or using the macro 'Edit.GotoBrace' several times. This tool provides a function which inserts comments after the closing brace automatically. The code snippet above would look like this:

Comments are only inserted for closing braces of if, while, for and switch statements.

If you don't want to insert comments automatically while editing, you can turn off this function. If you just don't want those comments at specific places you have to move the caret either upwards (instead of downwards which happens if you press enter) or click with the mouse so that the caret doesn't go to the line below the closing brace. Comments are also not inserted when the opening brace is less than two lines above.

#region/#endregion for C++

VS.NET introduced to possibility to outline portions of text in the code editor. That's a very useful feature wthat helps navigating through big bunches of code. But the outlined sections are not saved between sessions. VB and C# provide keywords to outline sections. In VB its '#Region' and '#End Region', in C# its '#region' and '#endregion'. Only for C++ MS didn't provide such keywords (at least I haven't found them yet). With this tool you can now enable that feature for C++ too. To prevent compiler errors for those who have not installed this tool I used '//#region' and '//#endregion' as the keywords. With the comment lines before the compiler won't complain. Use those keywords like this:

Whenever you open a document with such keywords the tool will automatically create outlining sections. The section are also created when you type the '//#endregion' keyword and a matching '//#region' is found. As you can see, you can easily nest the sections. The code above would then look like this:

This function can't be deactivated. If you don't want it, simply don't use those keywords

Search the web

These two small addons perform a simple web site search either in the google groups or on CP. Select a piece of text in the code editor, right click to pop up the menu and then select where to search for the selected text. That's all. The search results will be opened inside VS.NET.

Install

To install the tools, just double-click the *.msi file and follow the instructions. If the tools are not automatically activated the next time you start the IDE, then please activate them under Tools->Add-In Manager. Make sure you select both the addin and the box 'startup'.

All additional files needed for the tools are also packed in the installer, including Doxygen and the dot files. So you don't have to grab them separately from the web.

Source

Full source code is provided with these tools. The addin is written in VB.NET cause first there was just one simple tool that I wanted immediately - and VB is good enough for that. Then the tool grew and I added more functions. So the code is surely not the best example for good programming (no plan, no structure -> chaos). But maybe it might still be of interest for those who want to write their own addins. It shows a way to create submenus and how to add a toolbar.