Affordable, Php5, Web Design Programs - Tomcat Web Hosting

1330 Generating Documentation in Visual Studio Appendix E Outline E.1 Introduction E.2 Documentation Comments E.3 Documenting C# Source Code E.4 Creating Comment Web Pages E.5 Creating XML Documentation Files Terminology Summary E.1 Introduction A single programmer can implement most of the programs from this book. However, industrial software is more complex, and each project almost always requires the talent of several programmers. In such projects, communication among programmers is a necessity. When a programmer writes code for a class, programmers from the same group should understand how that class operates. For this reason, each programmer should document specific information on a class, such as the class s role in a system, the functionality that each method provides for the class and the purpose of each class variable. This documentation helps all programmers understand how classes can interoperate, and facilitates modification, use and extension of each class. To facilitate the creation of documentation for a project, Visual Studio .NET provides the XML documentation tool. This tool converts key pieces of information in source code such as the class s members, the hierarchy to which the class belongs and any other general remarks the programmer wishes to document to HTML1 or XML2 format. The programmer specifies the general remarks to be documented by placing them in special regions in the code, called XML documentation comments. In this appendix, we introduce Visual Studio .NET s documentation capabilities. We begin by discussing the format and structure of the XML documentation comments that the documentation-generation tool uses to create the documentation files. We then show how to generate the documentation through a LIVE-CODE example. We recommend reading through Chapters 8 10 before reading this appendix, because the examples presented in this appendix relate to the examples from these chapters. E.2 Documentation Comments Before the Visual Studio documentation-generation tool can generate documentation files, the programmer must insert XML documentation comments into the source files. These comments contain the information that the programmer wishes to document. The documentation- generation tool recognizes only single-line comments that begin with three forward slashes (///). An example of a simple documentation comment is ///