Content:
Getting the latest version
Introduction
Requirements and installation
Using DoxyComment
DoxyComment options
How it works
Extending DoxyComment
Quirks
This package is being updated from time to time. Below you will find links to the available downloads:
View the change log
Download DoxyComment add-in for Visual Studio 2005
DoxyComment is an add-in for Visual Studio 2005, which can help you insert comment blocks in C/C++ code. Comment blocks are generated based on the current context of the cursor. The add-in integrates nicely into Visual Studio, so you can bind your favourite short-cut keys to its commands.
The default comment blocks are compatible with the Doxygen documentation extraction tool. If you don't like the default comment blocks or you use another documentation extraction tool you can easily (without any knowledge of Visual Studio 2005 add-ins) write your own comment provider for the add-in.
| Requirement | Description |
|---|---|
| Microsoft Visual Studio | The current version of the add-in requires Microsoft Visual Studio 2005 (standard version or higher). Visual Studio should be installed prior to installing DoxyComment. |
| Doxygen (optional) | To extract the documentation (with default comment blocks) from your source code you need Doxygen. |
DoxyComment is distributed as an automatic setup archive. The setup will offer you automatic registration of the installation path in Visual Studio 2005's add-in search folders.
If you don't let the setup register the add-in path in Visual Studio 2005, you must manually added it to the add-in search folders (please see here for information on modifying the add-in search folders.
Note: If you have an old version of DoxyComment on your computer you must uninstall that version before installing the new version.
To remove DoxyComment you must close all instances of Visual Studio 2005 and remove the program in the Add or Remove Program control panel.
After installation of DoxyComment you should see a new toolbar called DoxyComment in Visual Studio 2005. The toolbar provides access to the essential DoxyComment commands. You can use standard Visual Studio 2005 customization to bind short-cut keys to the commands.
To use DoxyComment:
Open the source file containing the code element you wish to comment.
Place the cursor in the code element you wish to add a comment block to.
Invoke the Add Code Comment command from the DoxyComment toolbar.
The add-in will add a comment block at the top of the current code element.
Note: To insert comment blocks your source files must be project items (i.e. members) of an open C/C++ project. This is required because Visual Studio 2005 only provides a code model for project items.
So far the add-in supports insertion of comment blocks for the following code elements:
| Code element | Description |
|---|---|
| Namespaces | Global and nested namespaces are supported. Comment blocks are placed above the local definition of the namespace. |
| Classes, structs and unions | Global and nested classes, structs and unions are supported. Support for template parameters. Comment blocks are placed above the class, union or struct declaration. |
| Functions |
Globals and member (namespace and class, struct and union) functions
are supported. Comment blocks are placed above the definition of the
function (if one exists) or above the declaration. Note: Function parameters are considered part of the function comment block, so don't expect separate blocks for parameters. |
| Variables | Global and member variables are supported. Comment blocks are placed above the definition (if one exist) or above the declaration. |
| Enums | Comment blocks are placed above the declaration. Enumeration values have separate comment blocks placed directly above the value declaration. |
| Type definitions | Comment blocks are placed above the declaration. |
| Macros | Comment blocks are placed above the declaration. |
DoxyComment provides a number of options, which can be configured by the user. The options pages are integrated directly into the standard Tools Options dialog in Visual Studio 2005.
| Option name | Description |
|---|---|
| Indent comment blocks | Enabling this option will cause DoxyComment to inserted comment blocks at the same indentation level as the code construct being documented. |
| Insert at definition | Enabling this options will cause DoxyComment to insert comment blocks at the definition at all times. If you current cursor position is on a function or static variable declaration DoxyComment will try to find the definition of the same code construct and insert the comment (even if the definition is in a different file). |
| Active comment provider | This dropdown allows you to choose the active comment provider. Please see the Extending DoxyComment section for a description custom comment providers. |
This page shows the options offered by the individual comment providers.
DoxyComment inserts various types of comment blocks based on the current context of the cursor. To do this DoxyComment relies on an internal feature of Visual Studio 2005 called the Code Model. The code model is a data model of the current state of your project. Whenever you create, modify or delete classes, functions, parameters etc. the code model is updated to reflect this change instantly.
When you invoke DoxyComment to insert a comment block it will use the current position in the current active source file to determine the context in the code model. Based on the context DoxyComment will create a list of current code elements. DoxyComment then chooses the "closest" code element and builds a comment block for that element. The comment block is inserted at the top of the code element.
If you don't like my comment style or use a documentation extraction tool other that Doxygen you might want to change the way DoxyComment generates comment blocks. Fortunately for you DoxyComment has a simple interface, which allows you do just that. You will need to know how to implement an interface in Visual Studio 2005 and produce a class library.
The DoxyComment setup installs source and project files for an example custom provider. You can find the example files in the Test Provider sub-folder of your DoxyComment installation.
Note: If you go with the example project you need to modify (add/ remove) the DoxyComment assembly reference to match you installation path.
Below you can find a step-by-step guide to creating your own comment provider.
Create a new .NET Class Library project (any of the .NET languages will do).
Add references to the following assemblies:
| Assembly | Description |
|---|---|
DoxyComment.dll |
Assembly defines the ICommentProvider interface. |
envdte.dll |
Assembly contains various definitions for the Visual Studio 2005 environment. |
Microsoft.VisualStudio.VCCodeModel.dll |
Assembly contains definitions for the C/C++ code model. |
Note: You can remove the System.Data and System.Xml
references if you don't use them yourself.
Create a new public class, which implements the DoxyComment.ICommentProvider
interface.
Implement all methods of the ICommentProvider interface. Each method
has a parameter containing the appropriate code model element for which the comment
must be generated. All methods must output the comment block as an array of strings
(each string is placed on a separate line).
Compile your comment provider and copy the output dll to the Custom Providers
sub-folder of your DoxyComment installation folder.
When you restart Visual Studio 2005, DoxyComment will load your comment provider. You can activate your own comment provider on the Tools Options pages for DoxyComment (see DoxyComment options).
DoxyComment allows custom comment providers to expose properties to the end
user. The properties are shown in a PropertyGrid
on the Tools Options pages for DoxyComment.
Follow the below description to implement properties.
Add public properties with get and set accessors to your comment provider class.
Decorate the properties with attributes from the System.ComponentModel namespace. This will allow you to provide descriptions,grouping, custom editing etc. to your properties on the Tools Options page.
Mark all fields that contain property data with the CommentProviderProperty
attribute. This will allow DoxyComment to automatically collect all property related
fields for serialization.
When implemented you will see you properties appear on the Provider page of
the DoxyComment Tools Options pages. DoxyComment serializes the fields
marked with the CommentProviderProperty attribute under this
registry key:
HKEY_CURRENT_USER\Software\SourceForge.net\DoxyComment\<your provider's class name>
Note: If, during development of a custom provider, you change type
for any of the serialized fields you might need to delete the registry key
to have DoxyComment properly restore default values.
Below you find a list of issues related to the current version of DoxyComment.
The C/C++ code model in Visual Studio 2005 is unfortunately not always 100% accurate (as was the problem with the Visual Studio .NET 2003 code model). Sometimes certain code elements are missing. I've been looking for a pattern to this, but haven't so far been able to find the problem.
Symptom: You insert a comment block for a function and DoxyComment adds a comment block for the surrounding class. You insert a comment for a class and DoxyComment adds a comment for the surrounding namespace instead.
This is a clear sign that the code model is inaccurate. I've added a command to dump the code elements for the current cursor position in the Output window (DoxyComment pane). This way you determine if you are experiencing the problem or DoxyComment is doing something wrong.
If you remove DoxyComment, Visual Studio 2005 will automatically remove the add-in commands from the UI. Unfortunately the empty DoxyComment toolbar will remain (there is no way of associating a toolbar with an add-in). To get rid of it you must manually delete it using the Toolbar tab page on the Customize dialog (in the Tools menu).
| $Id: vs2005_addin.html 45 2006-09-04 22:53:16Z tgram $ |
|
|
| Copyright © 2006 by Troels Gram. |