Joseph Michael Pesch
VP Programming

Visual Studio XML Documentation Reference

by 8. March 2009 21:34

To add XML documentation:

1) Enable via Project Properties (on the Build tab).

2) Build project and you will receive warnings about all Public members that are not documented (you can double-click to add appropriate documentation in each section).

3) Install Sandcastle (http://www.codeplex.com/Sandcastle) and  Visual Studio 2008 SDK (http://www.microsoft.com/downloads/details.aspx?familyid=30402623-93ca-479a-867c-04dc45164f5b&displaylang=en)

4) Run Sandcastle program (in my case I ran it from C:\Program Files\Sandcastle\Examples\generic\SandcastleGui.exe)

5) Once you click on build the tool will generate HxS file under the sandcastle installation directory (named whatever you selected in the "Name" field). We will use this file to create a setup.exe which when installed integrates it with Visual Studio.

6) Open Visual Studio 2008 and click File -> New Project : In the new project dialog expand "Other Project Types" and select Extensibility. On the right hand side select "Help Integration Wizard" and enter a name for the project and click OK.  In the wizard that appears select "Setup project" and click Next.  In the next step select the HxS file we created in Step 5 above.  Visual Studio now creates 2 projects a Merge Module project and a setup project. Click on the setup project and modify its properties as needed.

7) Now compile the setup project to generate an MSI and a setup.exe file which when installed integrates the help with VS.NET.  You might have to close and re-open all instances VS.NET to see the change.  Now type in a class name in the code editor and press F1.  VS.NET should directly take you to the documentation associated with that class.

Below are the basic XML documetation tags you can apply to the source code for building the help file.

Documentation Sections

  • <summary>

    A short description of the item; describe the members of the type here.

    <summary>text</summary>
  • <remarks>

    The "Remarks" section of the documentation; specify overview information here.

    <remarks>text</remarks>
  • <example>

    The "Example" section of the documentation.

    <example>text</example>
  • <seealso>

    A link in the "See Also" section of the documentation.

    <seealso cref="member">text</seealso>

Member Documentation

  • <param>

    Describes a parameter to a method.

    <param name="name">text</param>
  • <returns>

    The return value of a method.

    <returns>text</returns>
  • <exception>

    The exceptions that can be thrown.

    <exception [cref="type"]>text</exception>
  • <value>

    Describes the value of a property.

    <value>text</value>
  • <permission>

    The permission applied to a member.

    <permission [cref="type"]>text</permission>

Text Formatting

  • <c>

    Format characters as code within other text.

    <c>code</c>
  • <code>

    Multiline section of code.

    <code>code</code>
  • <see cref>

    A link to a type, member or field in the current compilation environment.

    <see cref="member">text</see>
  • <see langword>

    Undocumented. A link to a keyword in the language of the current compilation environment, e.g. null.

    <see langword="keyword"/>
  • <paramref>

    A reference to a parameter within other text.

    <paramref name="name"/>
  • <list>

    A list of items.

    <list type="[bullet|number|table]">
        <listheader>
            <term>name</term>
            <description>text</description>
        </listheader>
        <item>
            <term>name</term>
            <description>text</description>
        </item>
    </list>
  • <para>

    A paragraph within other text.

    <para>text</para>
  • <include>

    Refer to comments in another file.

    <include file='filename' path='tagpath[@name="id"]' />

Tags: ,

Visual Studio

Comments are closed