Environment Setup (original) (raw)

#Environment Setup The easiest way to setup the filter is to add new Doc folder to your project/solution. The next steps describe this way to setup everything.

##Prepare your project Download the VB filter zip/tarball from the Releases page and extract the contents of the contained folder into your newly created Doc folder.

To checkout this repository using git inside your project folder:

git checkout https://github.com/sevoku/doxygen-vb-filter.git Doc

The package includes some examples and a preconfigured layout, optimized for VB project. Read more about layouts and how to customize them in the Doxygen manual.

###Gawk (Windows) When you are running Windows, you should copy gawk.exe to Doc\gawk.exe (see Requirements)

##Create a Doxyfile (Doxygen configuration) You can create a new Doxyfile from scratch using Doxywizard, or use one of the preconfigured Doxyfiles from the VB filter archive (for Windows or for Linux).

The following Doxyfile options are important for the VB filter to work:

###PROJECT_NAME This is the name of your Project shown everywhere in the documentation.

###FILTER_SOURCE_FILES This option enables the filter function. VB filter won't be applied without this!

FILTER_SOURCE_FILES    = YES

###INPUT_FILTER This is the full path to the wrapper script

Linux:

INPUT_FILTER           = "gawk -f /path/to/vbfilter.awk"

Windows:

INPUT_FILTER           = "\path\to\gawk.exe -f \path\to\vbfilter.awk"

Make sure gawk is in you path or add the full path to the gawk command.

###FILTER_PATTERNS If you have different source types in your project, you can define a filter for each extension. If no extension matches, then INPUT_FILTER will be used (if set).

The problem is that Doxygen does not support parametrized calls with this option. The executable must be parameterless, so you have to use a wrapper script, which passes the right parameters to gawk.

Linux:

INPUT_FILTER           = 
FILTER_PATTERNS        = *.vb=/path/to/vbfilter.sh

Windows:

INPUT_FILTER           = 
FILTER_PATTERNS        = *.vb=c:\vbfilter\vbfilter.bat

###FILE_PATTERNS This options defines which files Doxygen should analyze.

Since Doxygen has no native support for *.vb/*.bas/*.frm/*.ctl/*.cls files, you must specify the according extensions using this option.

You may also add other patterns to include in the documentation.

# VB.NET extenstions
FILE_PATTERNS          = *.vb

# Classic VB extenstions
FILE_PATTERNS          = *.cls \
                         *.bas \
                         *.frm \
                         *.ctl 

###OPTIMIZE_OUTPUT_JAVA

This option optimizes the Documentation for Java and C#.

Since the filter generates C#-like syntax, this option should be enabled.

OPTIMIZE_OUTPUT_JAVA   = YES

###EXTENSION_MAPPING

**This option is very important!**It defines which parser Doxygen will use, to analyze your sources.

VB files must be mapped to the csharp filter:

EXTENSION_MAPPING      = .vb=csharp \
                         .cls=csharp \
                         .frm=csharp \
                         .ctl=csharp \
                         .bas=csharp

If you are using an old unpatched Doxygen version and have simply renamed your *.vb files to *.cs, then you should disable mapping, because Doxygen uses automatically the right parser for *.cs files:

You could also try using the C++ parser, if you use an old unpatched Doxygen version and do not want to rename your sources. But the result will be not the best ;)

EXTENSION_MAPPING      = .vb=cpp
# try also disabling OPTIMIZE_OUTPUT_JAVA
OPTIMIZE_OUTPUT_JAVA   = NO
#OPTIMIZE_OUTPUT_JAVA  = YES

##Other useful options ###EXTRACT_*

The EXTRACT_* options are very useful, if you have undocumented parts, which should appear in the documentation.

EXTRACT_ALL            = YES
EXTRACT_PRIVATE        = YES
EXTRACT_STATIC         = YES
EXTRACT_LOCAL_CLASSES  = YES
EXTRACT_LOCAL_METHODS  = YES

###SHOW_DIRECTORIES

This option enables a "Directory" section in the documentation. This is very useful, if you have more that one Projects in your Solution.

###EXCLUDE_PATTERNS

Using this option you can exclude files/folders. To exclude the My folder, which is a part of most VB .NET projects use */My* pattern. You may also want to exclude the *.Designer* files generated by the forms designer.

EXCLUDE_PATTERNS       = */My* *Designer*

###STRIP_FROM_PATH

This option is very nice, if you do not want to show the full path of your project folder.

STRIP_FROM_PATH        = /path/to/project

###HAVE_DOT Set to YES, to enable Graphs in the documentation. GraphViz (see Requirements) has to be installed for this feature.