Chapter 28: XML Documentation


Overview

Up to this point in this book, you've seen the entire C# language and a whole bunch of things you can do with it, including both Web and Windows programming. Along the way you've seen, and made extensive use of, the IntelliSense feature in Visual Studio. This helpful tool dramatically cuts down on the amount of typing you have to do, because it suggests keywords, type names, variable names, and parameters as you type. It also makes it easier to remember what methods and properties you have at your disposal and often tells you exactly how to use them.

However, the classes you have made have suffered slightly here. While the classes and member names are suggested for you, no handy hints pop up telling you how to do things. To achieve the kind of behavior that you see with the .NET Framework types, you need to use XML documentation. XML documentation enables you to include syntax, help, and examples for the classes you create at the source code level. This information may then be used to provide IntelliSense information for Visual Studio as discussed above, but there are other possibilities. You can use XML documentation as a starting point for full, MSDN-link documentation of your projects. Or you can style the XML documentation using XSLT to obtain instant HTML documentation with very little effort. You have seen in earlier chapters just how versatile XML is, and you can use all of its power in the development and production lifecycle of your applications.

Documentation is particularly important when you are working as part of a team, since it allows you to show exactly how your types work. It can also be very useful to end users if you are creating an SDK or similar product where you expect people to use your classes from their code. Having the facility to create this documentation built into the tool you use to develop code is a very powerful feature. Despite the fact that it can be time-consuming to add XML documentation to your code, the end result is well worth it. Dropping text in as you develop can make things easier in the long run and also give you a handy quick reference that will help to avoid confusion when the amount of classes in your project starts getting out of hand.

In this chapter, you will learn:

  • How to add and view basic XML documentation

  • How to use XML documentation




Beginning Visual C# 2005
Beginning Visual C#supAND#174;/sup 2005
ISBN: B000N7ETVG
EAN: N/A
Year: 2005
Pages: 278

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net