C# Language Specification - Willy .Net

Appendix E Documentation CommentsE. Documentation CommentsThis clause is informative.C# provides a mechanism for programmers to document their code using a special comment syntax that containsXML text. Comments using such syntax are called documentation comments. The XML generation tool is calledthe documentation generator. (This generator could be, but need not be, the C# compiler itself.) The outputproduced by the documentation generator is called the documentation file. A documentation file is used as inputto a documentation viewer; a tool intended to produce some sort of visual display of type information and itsassociated documentation.A conforming C# compiler is not required to check the syntax of documentation comments; such comments aresimply ordinary comments. A conforming compiler is permitted to do such checking, however.This specification suggests a set of standard tags to be used in documentation comments. For C# implementationstargeting the CLI, it also provides information about the documentation generator and the format of thedocumentation file. No information is provided about the documentation viewer.E.1 IntroductionComments having a special form can be used to direct a tool to produce XML from those comments and thesource code elements, which they precede. Such comments are single-line comments of the form ///… ordelimited comments of the form /** … */. They must immediately precede a user-defined type (such as a class,delegate, or interface) or a member (such as a field, event, property, or method) that they annotate.Syntax:single-line-doc-comment::/// input-characters optdelimited-doc-comment::/** delimited-comment-characters opt */In a single-line-doc-comment, if there is a whitespace character following the /// characters on each of thesingle-line-doc-comments adjacent to the current single-line-doc-comment, then that whitespace character is notincluded in the XML output.In a delimited-doc-comment, if the first non-whitespace character on the second line is an asterisk and the samepattern of optional whitespace characters and an asterisk character is repeated at the beginning of each of thelines within the delimited-doc-comment, then the characters of the repeated pattern are not included in the XMLoutput. The pattern may include whitespace characters after, as well as before, the asterisk character.Example:/*** Class Point models a point in a two-dimensional* plane.*/public class Point{/// method draw renders the point.void draw() {…}}The text within documentation comments must be well formed according to the rules of XML(http://www.w3.org/TR/REC-xml). If the XML is ill formed, a warning is generated and the documentation filewill contain a comment saying that an error was encountered.433