Documentation Generation

The compiler can optionally produce an html documentation file for the project containing the following sections.

·        Project Information

• Debug table
• Call Tree

·        Procedure details

Project Information

This section contains information about the project itself. Including processor type, oscillator speed, configuration bits, and source files.

Debug Table

If debug mode is enabled, this section will contain the error code cross reference.

Call Tree

The call tree will appear here.

Procedure Details

This section contains details for every procedure in the program, including procedures from libraries.  XML tags inside comments can be used to include detailed information about the procedure, parameters, returns, and local variables. Items contained in this section include:

• Procedure summary (if XML tag is present)

•   Procedure statistics

• Parameter information (with XML information)
• Return variable information ( with XML information)
• Local variable information (if a matching XML tag is present)
• List of procedures this procedure is called from
• List of procedures this procedure calls

XML Tags

The documentation generator scans comments in the program looking for information to include in the output file in special XML tags.

The following XML tags are recognized:

• <summary>
• <param>
• <return>

•  <var>

In order for an XML tag to be associated with a procedure, the tag must be placed inside the procedure.

HTML tags are allowed inside an XML block

<summary> Tag

This is used to include a summary of the procedure.

Syntax:  <summary>  your summary goes here </summary>

Example:

Sub WaitForButton()
 
  ' <summary>
  '   Wait for the user to press and
  '   release the button.
  ' </summary>

<param> Tag

This will attach a description to a specific parameter variable.

Syntax: <param name="parameter name"> Description </param>

Example:

Sub SendByte(x as uByte)
 
  ' <param name="x"> This parameter contains the
  '                  value to send
  ' </param>
 

<return> Tag

Attach a description to a specific return variable.

Syntax: <return name="return variable name"> Description </return>

Example:

Function test(a as uByte)
 
    ' <return name = "x"> The return value </return>
  ' <return name = "y"> The error code</return>
 
  Dim x as uByte, y as uByte
 
  ...
 
End Function x,y

<var> Tag

Attach a description to a specific local variable. Only local variables with a corresponding XML tag will be included in the module details.

Syntax: <var name="variable name"> Description </var>

Example:

Sub xyz()
  Dim i as uByte  '<var name="i">Loop counter</var>