1. Documentation
Comments in C#

2. Comments in C# Building Documentation and Intellisense
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

3. Ordinary Comments in C#
Ordinary comments in C# have the same formats as in Java
A single or partial line comment begins with //
A multiline block of comments may consist of
Several lines of single line comments
Comments that begin with /* … and end at some later point with … */
Used for same purposes as in other languages
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

4. Examples: Ordinary Comments in C#
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

5. Header Comments for each Code File
Each C# code file you write should begin with a block of ordinary comments identifying the purpose of the file, the author, course, date, project, and so forth
An example is shown here
Introduction to the Syntax and Structure of C# Programs
December 6, 2018

6. XML Comments XML comments are used in C# for two primary purposes
Build documentation in a standard way that can be extracted to an XML file that may be formatted into a user’s manual or programmer’s guide, somewhat similar to Javadoc
Generate documentation to be used by Intellisense within any program that uses the class
This is important!
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

7. XML Comments XML comments have a common format
Begin with three forward slashes: ///
Use specific XML tags such as
<summary></summary>
<param name=“parameter_name"></param>
<returns></returns>
Designate specific items used by Intellisense
VS can auto-generate a skeleton of XML comments for you
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

8. Example
Type /// here
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

9. This skeleton of XML comments is generated instantly
Example, continued
This skeleton of XML comments is generated instantly
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

10. Fill in details as shown
Example, cont.
Fill in details as shown
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

11. Example, cont.
When typing a call to the method in other code, Intellisense provides a tooltip based on the description given in the XML comments
Note that this phrase is exactly the parameter description provided in the XML comment
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018

12. List of XML Comment Tags
(* denotes that the compiler verifies syntax.)
If you want angle brackets to appear in the text of a documentation comment, use < and >. For example, <text in angle brackets>.
List of XML Comment Tags
Tags
<c>
<para>
<see>*
<code>
<param>*
<seealso>*
<example>
<paramref>
<summary>
<exception>*
<permission>*
<typeparam>*
<include>*
<remarks>
<typeparamref>
<list>
<returns>
<value>
Decisions, Repetition, Code Snippets, Comments, and Intellisense
December 6, 2018