Game Development Reference
In-Depth Information
Figure 11.3 Missing comment warning in the Visual Studio C#.NET task list.
Supported XML Markup
There are quite a few supported XML tags and tag attributes that can be used for
different purposes when documenting your code; those tags are described in Table
11.1, along with instructions for when they should be used.
Keep in mind that in order to generate correct XML, the compiler must be given
correct documentation comments. Additionally, the compiler will generate a
warning and embed an error message in the documentation file if it is given XML
that is not well-formed. By well-formed XML, I mean XML that follows the rules
listed in the W3C Recommendation for XML 1.0.
A list of the standard tags available for inline documentation are presented in
Table 11.1.
The commenting structure is fairly loose and flexible, but you will notice that any
suggested comments to include will appear as warnings in your task list now that
your project is configured for commenting.
Keep in mind that since the compiler recognizes /// as a comment line when parsing
source code for embedded XML, the following documentation will be rejected by
the compiler:
/// <summary>
// </summary>
Public void FooBar() {}
Obviously, all documentation comments must be associated with a valid code con-
struct, otherwise they will be ignored. Valid code constructs are a class, struct,
enum, property, field, method, delegate, indexer, or event.
Namespaces are not considered code constructs because they are not limited to any one assembly,
so they cannot be considered a member of any one particular assembly.
Search Nedrilad ::

Custom Search