RightEdge - The Ultimate Backtesting and Trading System Development Platform

Using XML Comments for Documentation

This section contains information on:

Comment Samples
Supported Comment Tags
Generating Readable Documentation

 

RightEdge supports comments placed in code to create developer documentation of classes, methods and properties.  To take advantage of this, two things must be set.  First, the source code comments must conform to XML code comment styles that are described below.  Second, the trading system project must be set to emit an XML documentation file.  To set this, specify a valid XML filename in the XML Documentation File field in the Trading System Properties window.

In C#, code comments begin with three forward slashes (///).  In Visual Basic.NET, code comments begin with three apostrophes (''').

The samples below will demonstrate how to provide documentation to pieces of code at various levels.

Commenting a Class

C#

/// <summary>

/// This class contains information related to a single bar of data.

/// </summary>

public class BarData

{

 // Here's my BarData class items!

}

Visual Basic

/// <summary>

''' This class contains information related to a single bar of data.

/// </summary>

Public Class BarData

 ' Here's my BarData class items!

End Class

Commenting a Method

C#

/// <summary>

/// Called once for each new bar.

/// </summary>

/// <remarks>

/// This function is called for as many symbols that are active

/// within the system.  Perform actions that are bar and symbol

/// specific such as buy and sell evaluations.

/// </remarks>

/// <param name="symbol">Symbol being evaluated.</param>

/// <param name="bar">BarData for this symbol.</param>

public virtual void NewSymbolBar(Symbol symbol, BarData bar)

{

}

Visual Basic

''' <summary>

''' Called once for each new bar.

''' </summary>

''' <remarks>

''' This function is called for as many symbols that are active

''' within the system.  Perform actions that are bar and symbol

''' specific such as buy and sell evaluations.

''' </remarks>

''' <param name="symbol">Symbol being evaluated.</param>

''' <param name="bar">BarData for this symbol.</param>

Public Overridable Sub NewSymbolBar(ByVal symbol As Symbol, ByVal bar As BarData)

End Sub

Commenting an Enumeration

C#

/// <summary>

/// Order type to be submitted to the broker.

/// </summary>

public enum BrokerOrderType

{

 /// <summary>

 /// Market order.

 /// </summary>

 Market,

 /// <summary>

 /// Market on open order.

 /// </summary>

 MarketOnOpen,

 // ... etc

}

Visual Basic

''' <summary>

''' Order type to be submitted to the broker.

''' </summary>

Public enum BrokerOrderType

 ''' <summary>

 ''' Market order.

 ''' </summary>

 Market,

 ''' <summary>

 ''' Market on open order.

 ''' </summary>

 MarketOnOpen,

 ''' ... etc

End Enum

Supported Comment Tags

<code>

Enclose code sample text with this tag.

<para>

Paragraph text.  Allows for adding structure to text.

<see>

Allows for specifying a link to another topic.  Ex: <see cref="member" />

<seealso>

Specifies an item that will be displayed in the "See Also" section.

<param>

Indicates a function or method parameter.

<example>

A description for a code sample.

<summary>

The summary of the object.

<exception>

A reference to an exception.

<remarks>

Used to make comments or add additional information about a type.

<returns>

Description provided for a return value.

<value>

Description for a property.

Generating Readable Documentation

While the XML comment file is generated, this is hardly readable by consumers of the code or library.  At this point, there are a number of options to bring the documentation into a presentable state.

A common method is to apply XSLT to the XML file and generate HTML help pages.

Another method is to use an existing product that generates HTML help pages from the XML comments.  There are numerous commercial as well open source products that will handle this job.

The final method is to use an unreleased tool by Microsoft (code named "Sandcastle" at the time of this writing).

See Also

Trading System Properties