Using XML Comments

The XML Comments model is based on the XML Documentation Comments model developed by Microsoft. While originally developed for documenting C# source code, TechWriter extends the use of XML Comments for commenting databases.

If you are using or plan to use XML Comments for your database comments, you must set the comment format to XML Comments on the Database Settings dialog.

The XML Comments model includes support for the following tags that can be used for formatting.

XML Comments Tag Description

<c> Changes the font to bold.

<paramref name='...'/> Changes the font to italic.

<list type='number'> and <item> Formats a numbered list.

<list type='bullet'> and <item> Formats a bulleted list.

<list type='table'>, <listheader>,
<term>, <item> and <description>
Formats a table.

<see cref='...'> and <see href='...'> Represents a link. See Creating Topic Links for more information.

<param name='...'> Represents a list of names and descriptions of stored procedure parameters.

<returns> Represents the description of the value returned by a function.

<summary> Represents the description section of the comments.

<remarks> Represents the remarks section of the comments.

<para> Represents a normal paragraph.

XML Comments Tag	Description
<c>	Changes the font to bold.
<paramref name='...'/>	Changes the font to italic.
<list type='number'> and <item>	Formats a numbered list.
<list type='bullet'> and <item>	Formats a bulleted list.
<list type='table'>, <listheader>, <term>, <item> and <description>	Formats a table.
<see cref='...'> and <see href='...'>	Represents a link. See Creating Topic Links for more information.
<param name='...'>	Represents a list of names and descriptions of stored procedure parameters.
<returns>	Represents the description of the value returned by a function.
<summary>	Represents the description section of the comments.
<remarks>	Represents the remarks section of the comments.
<para>	Represents a normal paragraph.

In addition to the tags defined by XML Comments, TechWriter also supports the following extensions that can be used to achieve additional formatting results.

Extension Tag Description

<column name='...'> Represents the name and description of a database column.

<break/> or <br/> Represents a line break.

<sup> Represents a superscript.

<sub> Represents a subscript.

<h1>, <h2>, <h3> and <h4> Represents a heading.

<div class='othertitle'> Represents a document title.

<img src='...' /> References an image. The style attribute can also be specified that includes one or more of the following CSS properties:

height
width
text-align
See Referencing Images for more information.

Extension Tag	Description
<column name='...'>	Represents the name and description of a database column.
<break/> or <br/>	Represents a line break.
<sup>	Represents a superscript.
<sub>	Represents a subscript.
<h1>, <h2>, <h3> and <h4>	Represents a heading.
<div class='othertitle'>	Represents a document title.
<img src='...' />	References an image. The style attribute can also be specified that includes one or more of the following CSS properties: height width text-align See Referencing Images for more information.

Horizontal Alignment

The style attribute that contains a definition for the CSS text-align property can be used to specify specify horizontal alignment for the following tags:

<para>
<term>
<description>
<h1>
<h2>
<h3>
<h4>
<div>
<img>

Example

Below is an example of a comment that uses XML Comments:

<summary>
Table for storing employee information.
</summary>
<remarks>
This table contains information related to an employee.
</remarks>
<column name='EmployeeID'>ID of the employee.</column>
<column name='FirstName'>First name of the employee.</column>
<column name='LastName'>Last name of the employee.</column>
<column name='ManagerID'>ID of the employee's <see cref="Tables.CorpDb#Manager">manager</see></column>

Using Table Tags

Below is an example of a table created using XML Comment tags:

<list type="table">
   <listheader><term>Role</term><term>Description</term></listheader>
   <item><description>User</description><description>Typical end-user</description></item>
   <item><description>Admin</description><description>System administrator</description></item>
   <item><description>Manager</description><description>Project manager</description></item>
</list>

Note that the .NET XML Comments model does not provide a way to specify widths of columns within a table. If you use the annotation editor to edit tables and assigned column widths, those column widths will not be included in any exported annotations file that you create using the .NET XML Comments model.