Overview
Using Doxygen with VB is going to be a little painful. Because Doxygen doesn't have native support for VB we will need to use an input filter to change our vb code into C++ like code that Doxygen can recognize. This also means we probably won't be able to support as many documentation featurs (like the charts and maps that doxygen can automatically generate.)
Also I am not sure if everyone will need to setup Doxygen. We can discuss this further, but it may not be that important for every group member to be able to generate the documentation. We just need to ensure that we have Doxygen working on atleast one computer to create the docs for our project.
Coding (to Support Doxygen Documentation)
This guide has been lifted right from the README.txt included in the vbfilter. For a sample of how the comments will look and what is produced, take a gander at some VBSource files and their DoxygenOuput.
Doxygen Documentation conventions:
-
You have to start your class-files with a Doxygen-comment on top (like example 1 below).
-
The documentation must precede the function declaration. (see example 2)
-
If you want to let Doxygen detect method names in comments, you have to write them as C++ style full qualified names like 'MyClassOrModule::myFunction'. (see example 3)
-
There is a short-form for doxygen-comments, so you can just document one line using '' (see example 4)
- Start special tags with @-chartacters. Here is a link to a comprehensive list and desciption of the special tags available.
Caution:
- "on top" of the class file means inside the vb-editor, not in an ascii-editor (there are some Attribute-Entries before)!
- leave out the leading asterisk (*) inside a comment! *1
- you have to use the double asterisk at the end of a comment, too! *1
*1) in opposite to doxygens normal C++ documentation convention
Example 1: Class documentation
'/**
' The class CMyClass is a sample class for Doxygen documentation.
'
' @author some weired guy
' @version 1.0 first documented version
'**/
Example 2: Property Documentation
'/**
' Property that gives information about its pending state.
' @return [As Boolean] is True, while object is pending ' @version 1.0 first documented version
'**/
Public Property Get isPending() As Boolean
isPending = mdData.document Is Nothing
End Property
Example 3: Sub documentation (with a link to another function in the header comment)
'/**
' Please use ViewContainer::showEverything() after you have added something
'**/
Public Sub addSomething(ByVal id As Long)
' (...)
End Sub
' /**
' Shows every item you have added with ViewContainer::addSomething()
' **/
Public Sub showEverything()
' (...)
End Sub
Example 4: Documenting a single line
'' this is a string var;
Private mStringVar As String
VBfilter setup
A VB filter has been created for doxygen (by Mathias Henze). However several files are needed for this to work properly:
1) vbfilter.bat - this batch file that will be specified as the input filter in the doxygen configuration file
2) vbfilter.awk - awk file that specifies which text will be filtered out of our VB files
3) SlashConverter.exe - converts backwards slashes to forward slashes
4) sh.exe - ported unix tool
5) tee.exe - ported unix tool
6) gawk.exe - ported unix tool
I have zipped these files along with the readme that came with the tool:
vbFilter.zip.
All these files will need to be in the same directory for the input filter to work properly. There is an additional file "dot.exe" inside the zip file that is needed to support a map feature. I installed graphviz to get the dot.exe, but I am not sure if the entire software program is actually needed. Hence I have just included the dot.exe in the zipfile, but graphviz may actually need to be installed (graphviz download).
Doxygen Setup
Intially doxygen will need to be downloaded (download link).
Once doxygen is running a config file will need to be created that uses the vbfilter.bat file as an input filter. Using the GUI interface (by running doxywizard.exe) you will have 3 choices of how to create the configuration file. We want expert - because we're kind of a big deal :) In the expert options there are several things to be set:
-
Build Tab
1) All the following should have checkmarks (everything else should not):
- EXTRACT_ALL
- EXTRACT_PRIVATE
- EXTRACT_STATIC
- EXTRACT_LOCAL_CLASSES
- EXTRACT_LOCAL_METHODS
- SHOW_INCLUDE_FILES
- INLINE_INFO
- SORT_MEMBER_DOCS
- GENERATE_TODOLIST
- GENERATE_TESTLIST
- GENERATE_BUGLIST
- GENERATE_DEPRECATEDLIST
- SHOW_USED_FILES
2) MAX_INITIALIZER_LINES should be set to 30
3) everything else should be left blank/empty
-
Input Tab
1) The directory that holds the VB code should be added to the INPUT box (ie: the first box)
ex: C:/LEGOROBOT/GUIprototypes/
2) The string "*.vb" should be added to the FILE_PATTERNS box. All other strings can be removed.
3) The INPUT_FILTER should be set as follows:
INPUT_FILTER = drive:/path/to/unxtools/vbfilter.bat drive:\path\to\unxtools
ex: C:/LEGOROBOT/GUIprototypes/vbFilter/vbfilter.bat C:\LEGOROBOT\GUIprototypes\vbFilter
4) FILTER_SOURCE_FILES should be checked (it's at the bottom)
5) All other options should be okay with their default value
-
Source Browser Tab
1) We can experiment with this. Checking all the boxes is suppose to add the source code. However for our VB files it is only adding the variable and function definitions.
-
Dot Tab
1) To get rid of error messages complaining the dot.exe cannot be found, add the path in DOT_PATH
ex: C:/~THINKING MACHINE/TOOLS/GRAPHVIZ/bin
I believe those are all the changes I made for the config file. Next you will save a copy of the config file and choose an output directory (where the documentation will be generated.) Finally click Start and the documentation should be created.
The configuration I specified is a guideline of what worked for me. We may want to experiment further to find the best settings for our program. Here are some useful links from my testing:
ConfigFile - a link to the config file I created
DoxygenOuput - a link to the html it created
VBSource - the test source that was used to generate the documentation (warning - because I was messing around with these files, the vb code will no longer compile)
Comments (0)
You don't have permission to comment on this page.