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 websites.

If you are using or plan to use XML Comments for your website comments, you must set the comment format to XML Comments on the Website 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.

<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.
<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

<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
<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>
Standard CSS styles
</summary>
<remarks>
This CSS style sheet contains the standard style definitions used for externally
facing websites.
</remarks>

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.