Archive for the Category XML

 
 

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.

DataSetDocument

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

How to Use XML Documentation

Alan Dean wrote three posts about using Xml documentation in your code

[How To] Use XML Documentation (Part 1: The Overview)

[How To] Use XML Documentation (Part 2: The Detail)

[How To] Use XML Documentation (Part 3: Complex tables)


Page 2 of 212