How to document DataSets
Most online resources talks about how to document class methods and properties .In this post I’m going to show how to comment your datasets to create professional and more convenient documentation .
Take a look at picture below.
To achieve such results, organize your XML tags in this way
<summary>
[Method Sumamry]
</summary>
<value>
The dataset contains the following tables
<remarks>
<list type="table">
<listheader>
<term>Table</term>
</listheader>
<item>
<term>[Table Name]</term>
</item>
</list>
</remarks>
Table [Table Name] contains the following fields:
<remarks>
<list type="table">
<listheader>
<term>Field</term>
<description>Description</description>
</listheader>
<item>
<term>[Column Name]</term>
<description>[Column Description]</description>
</item>
</list>
</remarks>
</value>
The Comment snippet below, along with NDoc produced the MSDN-style formatted document.
/// <summary>
/// Gets the history entries.
/// </summary>
/// <value>
/// The dataset contains the following tables
/// <remarks>
/// <list type="table">
/// <listheader>
/// <term>Table</term>
/// </listheader>
/// <item>
/// <term>History</term>
/// </item>
/// </list>
/// </remarks>
///
///
/// Table History contains the following fields:
/// <remarks>
/// <list type="table">
/// <listheader>
/// <term>Field</term>
/// <description>Description</description>
/// </listheader>
/// <item>
/// <term>Method (<see cref="System.String"/>)</term>
/// <description>Method name</description>
/// </item>
/// <item>
/// <term>ExecutedTime (<see cref="System.DateTime"/>)</term>
/// <description>When the specific method was executed</description>
/// </item>
/// <item>
/// <term>Result (<see cref="System.float"/>)</term>
/// <description>Method result</description>
/// </item>
/// </list>
/// </remarks>
/// </value>
Technorati Tags: Programming Net DataSet System.Data Document CHM
