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

If you are using or plan to use XML Comments for your web service comments, you must set the comment format to XML Comments on the Web Service 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 method arguments.

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

<example> Represents an example instance of an element.

<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 method arguments.
<returns>	Represents the description of the value returned by a method.
<example>	Represents an example instance of an element.
<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

<enum name='...'> Represents the name and description for an enumerated value.

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

<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
<enum name='...'>	Represents the name and description for an enumerated value.
<fault name='...'>	Represents the name and description of a fault.
<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>
Method for getting a weather forecast.
</summary>
<remarks>
This method can be used to get the weather <see cref="Elements.Weather#Forecast">forecast</see> for a range of days by specifying
the starting and end dates. Both dates must be no later than 10 days from the current date.
</remarks>
<param name='startDate'>Specifies the first day of the weather forecast.</param>
<param name='endDate'>Specifies the last day of the weather forecast.</param>
<returns>The weather forecast for the specified date range.</returns>

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.