XML Documentation Sample

Switch View

XML Documentation Sample

Collapse All

Language Filter

This page is specific to

Microsoft Visual Studio 2008/.NET Framework 3.5

Other versions are also available for the following:

Visual C# Samples

XML Documentation Sample

This sample shows how to use XML to document code. For more information, see XML Documentation Comments (C# Programming Guide).

To get samples and instructions for installing them

Do one or more of the following:
- On the Help menu, click Samples.
  
  The Readme displays information about samples.
- Visit the Visual Studio 2008 Samples Web site. The most recent versions of samples are available there.
- Locate samples on the computer on which Visual Studio is installed. By default, samples and a Readme file are installed in drive:\Program Files\Microsoft Visual Studio 9.0\Samples\lcid. For Express editions of Visual Studio, all samples are located online.

For more information, see Locating Sample Files.

Security Note:
This sample code is intended to illustrate a concept, and it shows only the code that is relevant to that concept. It may not meet the security requirements for a specific environment, and it should not be used exactly as shown. We recommend that you add security and error-handling code to make your projects more secure and robust. Microsoft provides this sample code "AS IS" with no warranties.

To build the XML Documentation sample within Visual Studio

In Solution Explorer, right-click the project and then click Properties.
Open the Configuration Properties folder and then click Build.
Set the XML Documentation File property to XMLsample.xml.
On the Build menu, click Build.
The XML output file will be in the debug directory.

To build the XML Documentation sample from a command prompt

To generate the sample XML documentation, type the following at a command prompt:
```
csc XMLsample.cs /doc:XMLsample.xml
```
To see the generated XML, type the following command:
```
type XMLsample.xml
```

Tasks

How to: Use the XML Documentation Features (C# Programming Guide)

Concepts

Visual C# Samples

C# Programming Guide

Tags

: Add a tag

Community Content

Add new content

Annotations

where's the tofu? (rhetorical) ~~ XML Documentation Sample

gerry lowry ... Thomas Lee | Edit | Show History

Since this article is titled "XML Documentation Sample", it's fair for one to expect to easily find a decent SAMPLE that demonstrates the use of XML in source code as well as how to actually cause documentation to be produced from the XML that one inserts in her/his source code. The links on *this* page are far too generic.

MORE INFORMATION
---------------------------
The tutorial "XML Documentation Tutorial" is useful (http://msdn.microsoft.com/en-us/library/aa288481.aspx).
{The path to this deeply buried article is:
-- MSDN, MSDN Library, Development Tools and Languages, Visual Studio .NET,
Visual Basic and Visual C#, Reference,
Visual C# Language, C# Programmer's Reference, C# Tutorials,
XML Documentation Tutorial}

Note: if you type "///", space, "less than symbol", you'll see some Intellisense for eight of the tags from
http://msdn.microsoft.com/en-ca/library/5ast78ax.aspx
"Recommended Tags for Documentation Comments (C# Programming Guide)"

Note also: if you type "///", space, "less than symbol", you can type any tag;
just type a tag as you normally would, e.g.: "less than symbol", text, "greater than symbol":

             /// <returns>

             /// <gerry>

Intellisense will automatically complete the closing tag:

             /// <returns></returns>

             /// <gerry></gerry>

You will likely want to use the "Recommended Tags" (see above link).

I have started using Sandcastle to build a compiled help (.chm) file.
Sandcastle - Documentation Compiler for Managed Class Libraries
-- http://www.codeplex.com/Sandcastle
"Sandcastle produces accurate, MSDN style, comprehensive documentation
by reflecting over the source assemblies and optionally integrating XML Documentation Comments"
-- http://www.codeplex.com/Sandcastle/Release/ProjectReleases.aspx?ReleaseId=13873
Sandcastle is not working as expected, possibly my error. More on this later when I understand Sandcastle better.

Regards, Gerry (Lowry)

References:
Using IntelliSense: http://msdn.microsoft.com/en-us/library/hcw1s69b.aspx
Processing the XML File (C# Programming Guide): http://msdn.microsoft.com/en-us/library/fsbx0t7x.aspx
/doc (Process Documentation Comments) (C# Compiler Options): http://msdn.microsoft.com/en-us/library/3260k4x7.aspx
XML Documentation Comments (C# Programming Guide): http://msdn.microsoft.com/en-us/library/b2s063f7.aspx