Click or drag to resize
Sandcastle Help File BuilderWalkthrough: Enabling and Using XML Comments

This walkthrough will describe the steps needed to enable XML comments file output in your Visual Studio projects, provides information on where to get more information on using XML comments to decorate your code, and describes how to open help file builder projects from within Visual Studio.

Enabling XML Comments File Generation

In order to create a help file that contains reference content (API documentation), you must enable XML comments in your Visual Studio projects so that an XML file is generated to contain them when the project is built.

Note Note

If you are trying to document a website project, see the Documenting Web Projects topic for some necessary information as they are unlike other Visual Studio projects and require additional steps in order to generate XML comments files.

Tip Tip

If not using the Visual Studio IDE, the various managed language compilers support a /doc command line option that will produce the XML comments file. See your language compiler command line option documentation for details.

All Projects Except Managed C++ Projects

  1. In the Solution Explorer, right click on the project and select Properties.

  2. Select the Build property page.

    Note Note

    The XML comments filename is a configuration option. As such, you can either select the All Configurations option at the top of the page to set the XML comments options for all configurations at the same time or select each configuration individually and repeat the next steps for each one.

  3. In the Output section, check the checkbox next to the Xml documentation file text box and specify a name for the XML file. Although not required, a common convention is to name the XML comments file after the related assembly (except with a .xml extension). The assembly name can be found on the Application property page.

  4. If you have a solution with multiple projects that need to be documented, repeat the above steps for each project in the solution. It is recommended that you give each project's XML comments file a unique name.

If documenting a managed C++ project, the procedure differs and you need to follow these steps instead.

Managed C++ Projects

  1. In the Solution Explorer, right click on the project and select Properties.

  2. Expand the Configuration Properties category and then expand the C/C++ sub-category and select the Output Files option below it.

    Note Note

    The XML comments file option is a configuration option. As such, you can either select the All Configurations option at the top of the dialog box to set the XML comments options for all configurations at the same time or select each configuration individually and repeat the next step for each one.

  3. In the Output Files options, change the Generate XML Documentation Files option to Yes (/doc).

  4. By default, the comments file is named after the project target with a .xml extension and is placed in the target folder. If you want to change the name, select the XML Document Generator category below the Configuration Properties category and change the filename using the Output Document File property.

  5. If you have a solution with multiple projects that need to be documented, repeat the above steps for each project in the solution. If you explicitly specify a name for the comments file, it is recommended that you give each project's XML comments file a unique name.

Once the above has been done, Visual Studio will create the XML comments file each time the project is built.

Decorating Your Code

In addition to setting the project option to create the file, you must also add XML comments to your source code. At a minimum, you should add a <summary> tag to each public type and to the public and protected members of those types. There are many other tags available that will help improve the quality of your documentation.

For a comprehensive list of XML documentation elements and a description of their attributes and usage, see the Sandcastle XML Comments Guide installed as part of the Sandcastle tools. Basic information on XML comments and how to use them can also be found at either XML Documentation Comments (C# Programming Guide) or Documenting Your Code with XML (Visual Basic).

Although it is not mentioned in the XML tag documentation, you can use HTML markup within your XML comments to provide additional formatting, embed images, etc. See the FAQ for more information.

Next Steps

Now that you have enabled XML comments in your project and added some comments to your code, you are ready to create your first help file builder project.

See Also