Documentation COMMENTS IN C Comments in C Building

Documentation COMMENTS IN C#

Comments in C# Building Documentation and Intellisense Decisions, Repetition, Code Snippets, Comments, and Intellisense May 25, 2021 2

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 May 25, 2021 3

Examples: Ordinary Comments in C# Decisions, Repetition, Code Snippets, Comments, and Intellisense May 25, 2021 4

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 May 25, 2021 5

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 May 25, 2021 6

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 May 25, 2021 7

Example Type /// here Decisions, Repetition, Code Snippets, Comments, and Intellisense May 25, 2021 8

Example, continued This skeleton of XML comments is generated instantly Decisions, Repetition, Code Snippets, Comments, and Intellisense May 25, 2021 9

Example, cont. Fill in details as shown Decisions, Repetition, Code Snippets, Comments, and Intellisense May 25, 2021 10

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 May 25, 2021 11

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