Documenting your sources

#Documenting VB sources for use with Doxygen

The Doxygen Visual Basic filter recognizes many types of documentation blocks.

Each Line of a comment block must begin with three apostrophes (''')

''' valid documentation block
''' with three apostophes as prefix

or one apostrophe and a tag in the first line

' <summary>
' valid documentation block
' with single quotation mark and a tag in the first line
' </summary>
' \brief an other valid documentation block
' with single quotation mark and a tag in the first line

ATTENTION VB6 USERS: comment blocks with only one apostrophe and no tag in the first line will be ignored!

' ignored documentation block
' with single quotation mark but WITHOUT a tag in the first line

Different comment blocks can be separated by empty lines.

All tags (supported by Doxygen) can be used as usual:

• Visual Studio 2005+ XML Commands
• default Doxygen commands
• Doxygen HTML commands

##Class/Member description

A class or class member documentation must be right above its declaration.

Example (Classic Style):

' \brief Short description of the Class Test
' \remarks
' This text describes 
' the class
Public Class Test
    ' \brief Short description of the member SomeString
    ' \remarks This text describes the member
    Public SomeString As String
End Class

Additionally the default Visual Studio 2005+ comment style can be used, where the members are documented with comments beginning with three apostrophes (''') as prefix in every line.

Example (VB.NET Style):

''' <summery>Short description of the Class Test</summary>
''' <remarks>
''' This text describes 
''' the class
''' </remarks>
Public Class Test
    ''' <summery>Short description of the member SomeString</summary>
    ''' <remarks>
    ''' This text describes the member
    ''' </remarks>
    Public SomeString As String
End Class

##VB.NET - File Header

If a documentation block begins in the first line of a file, it will be treated as a documentation header block.

The @file line will be automatically added to the header with the corresponding file name. Example:

' \brief Short description of the file
'
' This text describes 
' a file and must start in the first
' line of the file.
Option Explicit

Imports XY

' \brief short class description
Public Class Z
End Class

Example Result (processed by filter):

/**
 * @file CurrentFilename.vb
 * \brief Short description of the file
 *
 * This text describes 
 * a file and must start in the first
 * line of the file.
 */
using XY;
/**
 * \brief short class description
 */
public class Z
{ }

##Classic VB - File Header

The filter can not recognize header documentation blocks automatically in classic VB, because there are no Class definitions (in classic VB one file describes always exactly one module, class, control or form).

The first comment block in the file will be always recognized as the description of the class, form, or whatever the file contains. To force a comment to be associated with the file itself (and not it's content), the Doxygen command \file must be used.

' \brief VB6 class example'
' \remarks class description

' \file VB6Class.cls
' \remarks description of the file itself

The second comment block begins with a \file command and will be treated as a file description by Doxygen.

##Inline member comment

In addition to full member descriptions, inline comments are supported. These comments must be placed at the end of a line, where the declaration is. Multiline Enum declarations are also supported.

Public Enum eTest
    Value1     ' first value
    Value2 = 2 ' second value
    Value3     ' third value
End Enum

Class SomeClass
    Public SomeValue As Integer   ' member documentation
End Class

##Comments inside members (real code comments)

Comments initiated with a single quotation mark (') will be ignored (except inline comments!), if they do not begin with an XML-/Doxygen-Tag or three apostrophes (''').

This is important, if documenting Classic VB code! Only tagged comments will be recognized! (Read about valid comment blocks at the beginning of this article.)

' <summery>Brief description of the Class Test</summary>
' <remarks>
' This text describes 
' the class
' </remarks>
Public Class Test
    ' Brief description of the member SomeString
    ' will not be visible, because it has no tags
    ' and only one apostrophe as prefix
    Public SomeString As String
End Class

Example Result (processed by filter):

/**
 * <summery>Brief description of the Class Test</summary>
 * <remarks>
 * This text describes 
 * the class
 * </remarks>  
 */
public class Test
{
    public String SomeString;
}