XML Documentation

The XML Documentation feature allows you to generate a file with documentation of your source code in XML format. The XML file includes elements such as References, Projects, Files, Procedures, Parameters, Controls, etc. Each element such as Reference, Procedure, Parameter, etc. includes subelements with relevant properties. For example, the Parameter element has the Type, Optional, Default Value, etc.

MZ-Tools offers the following ways to generate XML documentation:

• The Tools | MZ-Tools | Other Utilities | Generate XML Documentation... menu: with this menu you can generate XML documentation of all the files of all the projects.
• The Generate XML Documentation... context menu of a project in the Project Explorer of Visual Basic: with this menu you can generate XML documentation of all the files of the selected project.
• The Generate XML Documentation... context menu of a file in the Project Explorer of Visual Basic: with this menu you can generate XML documentation of the selected file.
• The Other Utilities | Generate XML Documentation... menu on the MZ-Tools toolbar: with this menu you can generate XML documentation of all the files of all the projects.
• The shortcut customized in the Options window, Shortcuts tab: with this shortcut you can generate XML documentation of all the files of all the projects.

The XML file also includes comment line elements for module and procedure elements whose content is extracted from the source code (provided you have entered them). Comments are extracted line by line as literals, so you can use any format for them, that is, they do not need to be XML compliant.

Although not required, MZ-Tools allows you to include a reference to an XSLT template in the XML file when it is generated (Options window, General tab). This XSLT template allows you to format the XML file for viewing it with Microsoft Internet Explorer 5.0 or higher.

There are a lot of uses for the XML file. As example, an XSLT template is provided that you can customize which uses also CSS, JavaScript and DHTML to expose the XML documentation as a HTML report for documentation purposes.

Remarks:

• Although MZ-Tools does not require the Microsoft XML Parser to generate the XML file, you will need Microsoft XML Parser 3.0 SP1 or higher in Replace Mode (with the xmlinst.exe utility) to use XSLT templates. See the MSDN Knowledge Base article Q278969 "INFO: How to Redistribute the Microsoft XML Parser".
• Ensure that the source code can be compiled without errors before running this feature.
• This feature retrieves the values of properties of controls, including UserControls. That means that if you have a UserControl with a Property Get that is not intended for design-time, you must ensure that it can be used only at run-time checking the Ambient.UserMode value:
   
  Public Property Get Property1() As Integer
   
    If Ambient.UserMode = True Then    ' Do not execute at design-time
       MsgBox "Test"
       ...
    End If
   
  End Property
   
  Otherwise, the MsgBox statement would be executed when generating the XML documentation.

See Also:

General Customization

Shortcuts Customization