Web Design that taps into the haromny and vision of your dreams.

XML Documentation in Visual Studio

Documenting code with XML

Written By on in C#

420 words, estimated reading time 2 minutes.

Visual Studio 2003 and onwards provides the ability to generate project documentation using comments in the code with embedded XML tags. These can be easily converted to a printable or human readable document using style sheets.

Using Visual Studio Series
  1. Getting Started with Visual Studio
  2. Using the Visual Studio Integrated Development Environment
  3. Using the Visual Studio Debugger
  4. XML Documentation in Visual Studio
  5. Using Microsoft .Net Command Line Tools
  6. What is an Assembly in Microsoft .Net?
  7. Creating and Using a .NET Assembly in C#
  8. Creating and Implementing Satellite Assemblies
  9. Creating Strong Named Assemblies in Microsoft .Net
  10. Visual Studio Task List
  11. Resources and Localisation in C# Projects
  12. Localising Microsoft .Net Applications with C#
  13. Using Resource Files in C# Applications
  14. Using XSD Tool to Generate Classes from XML
  15. 10 Visual Studio Tools You May Not Know About

This article relates to an old version of the .Net Framework. While the contents are still relevant, future versions of the framework may change, or improve upon, the contents of this article.

The code editor will automatically provide the XML tags, all you need to do is to fill in the text as you code. XML documentation is slightly different from normal code comments in that it uses three forward slashes (///) instead of the two. The editor will provide a list of tags that you can use, including a title and description for methods.

By typing /// in front of a method, the editor will auto-complete a basic documentation layout for that method.

/// <summary>
///
/// </summary>
/// <param name="args"></param>
static void Main(string[] args)
{
}
 

All you need to do is fill in a summary of the method (what it does, called by, any data it returns etc...) and a description of the parameters it takes.

Using IntelliSense (Ctrl+Space) you can bring up a list of tags that can be used, including examples, see also and permissions.

It is good practice to comment your code as you progress.

A well-commented application permits a developer to fully understand the structure of the application and how the various aspects interact with each other. It also allows other developers to understand the project much quicker as they spend less time trying to work out what everything does.

When your code is complete and commented you can generate documentation by configuring the project properties.

Either right-click the project in the Solution Explorer or select Properties from within the Project menu. At the bottom of the build tab, there is an option to generate XML Documentation. Just enter a path for the documentation to be stored within. It will default to your project directory + "bin/debug/.xml".

You can also use the command line tool, csc.exe, to generate a documentation file:

csc program.cs /doc:my-xml-documentation.xml

Additionally, the text within the

tags are used by IntelliSense as the method description when prompting for info in the code designer. If you are developing code that will be reused by different people it is highly recommended that each method has at a minimum a summary section.

IntelliSense demonstration
IntelliSense demonstration

The resulting XML from the documentation isn't very readable to humans, but we can use an XML transformation to generate an HTML version. There is a good example style sheet on codeproject.com to download and use.

Last updated on: Friday 23rd June 2017

 

Comments

There are no comments for this post. Be the first!

 

Leave a Reply

Your email address will not be published.





If you find something abusive or that does not comply with our terms or guidelines please flag it as inappropriate.

Copyright © 2001-2018 Tim Trott, all rights reserved. Web Design by Azulia Designs

This web page is licensed for your personal, private, non-commercial use only.

Disclaimer, Privacy & LegalSitemapContact Me