Game Development Reference
Once a valid file path is specified, when the project is compiled, an XML file will
be generated that contains all the XML comment tags that were embedded in the
You may have some projects that will be compiled from the command line, and the
way to generate the XML documentation file in such a situation is by using the /doc
csc /doc:NDocExample.xml NDocExample.cs
In either situation, command line or through an IDE, the /doc compiler switch will
be ignored in a compilation that uses the /incremental build switch. Therefore, you
should use the /incremental- switch to disable the incremental build and ensure
that your XML documentation file remains up-to-date.
After your project is configured to output an XML documentation file, any com-
ments that are suggested to be included will not prevent compilation, assuming
you do not have warnings set to errors, but will instead show up as a warning in
the task list. You can simply double-click on the warning in the task list to jump to
the location where a comment should be added, much as any other error or warn-
ing can be navigated to.
Figure 11.2 shows the source code location where the comment should be inserted.
Figure 11.2 Example of a source code location that should be commented.
Figure 11.3 shows a comment missing from the constructor of MainForm , and sug-
gests that it be added for standards compliance.
An extremely useful feature that improves documentation productivity is a macro
that inserts basic commenting tags for a particular method or class. Simply place
the text insertion pointer on the line above the method or class header in question
and press the / (forward slash) key three times. A summary tag block is inserted,
along with all the parameter tags for the method, if applicable. Additional tags can
be added to the basic blocks that were inserted, but they have to be added manually.