This covers the basics of using XML comments to document your .NET code, including the most commonly used tags.

1. XML Comments

2. Comments: Why?
•
Communicates the expected behavior of your
code to other developers
•
Makes you think about the code you’re writing

3. XML Comments: What?
•
An XML Comment is an XML-based
documentation that precedes the block to which
they refer
•
All XML comments in a project are compiled to a
single XML documentation file (based on project
property setting)
•
Not metadata (i.e. not included in the compiled
assembly)

4. XML Comments vs Inline

5. XML Comments vs Inline

6. XML Comments: Why?
•
Standardized format
•
Extensible (XML)
•
Tool support
•
Intellisense
•
Object Browser
•
Code Comment Web Report

7. XML Comments: Why?
•
Quick creation of help files/documentation
•
GhostDoc
•
Sandcastle

8. Documentation Sections
•
The following tags correspond to the major
documentation sections
•
Can be applied to any type or type member

9. <summary>
•
A succinct description of a type or type member
•
•
•
Focuses on "what", not “how”
Displayed by Intellisense
Template: The name method/property/etc [...]

10. <summary> example
•
Not recommended

11. <summary> example
•
Recommended

12. <summary> intellisense

13. <summary> output

14. <remarks>
•
Detailed information about a type or type
member
•
Supplemental to the information in the
<summary> tag (can include "how")

15. <remarks> example

16. <remarks> output

17. <exception cref=“…”>
•
Specifies which exceptions a method, property,
event, or indexer can throw
•
The cref attribute is checked by the compiler
•
Displayed by Intellisense (sort of)
•
Can have multiple per type member

18. <exception> example

19. <exception>
intellisense

20. <exception> output

21. <example>
•
Denotes a block of code that demonstrates the
use of the type or type member being
documented.
•
Used in conjunction with the <code> tag.

22. <example> example

23. <example> output

24. <permission cref=“…”>
•
Indicates the permission applied to a member
(via a PermissionSet)
•
Outputs to the .NET Framework Security section.
•
The cref attribute is checked by the compiler.

25. <permission> example

26. <permission> output

27. <seealso>
•
Specifies a link to another documentation page
in a "See Also" section.
•
cref, langword, or href attributes are supported.

28. <seealso> example

29. <seealso> output

30. Member Documentation
•
The following tags are applicable to specific
types of type members.

31. <param name=“…”>
•
Describes a method’s parameter.
•
Also applies to constructors and destructors
(finalizers).
•
The name attribute is checked by the compiler.
•
Each tag describes one parameter.
•
Displayed by Intellisense

32. <param> example

33. <param> Intellisense

34. <param> output

35. <returns>
•
Describes the return value of a method

36. <returns> example

37. <returns> output

38. <value>
•
Describes the value of a property (e.g. what the
property’s value represents)

39. <value> example

40. <value> output

41. Formatting Tags
•
The following tags provide formatting instructions
for rendering documentation output.
•
Highly recommended if you're generating
documentation (using a tool like Sandcastle).

42. <c>
•
Indicates that one or more words in a tag’s
content should be interpreted as code.
•
Should not be used for standalone blocks of
code; use <code> instead.

43. <c> example

44. <c> output

45. <code>
•
Denotes a section of comments that should be
read as code.
•
Typically displayed in documentation output in a
monospaced font.

46. <code> example

47. <code> output

48. <paramref name=“…”>
•
Indicates that a word in a comment refers to a
parameter.
•
The name attribute is checked by the compiler.

49. <paramref> example

50. <typeparam name=“…”>
•
Describes a generic type parameter.

51. <typeparam> example

52. <typeparam> output

53. <typeparamref name=“…”>
•
Identifies a word that refers to a generic type
parameter.

54. <typeparamref> example

55. <typeparamref> output

56. <see>
•
Specifies an inline link to another piece of
relevant information.
•
cref, langword, or href attributes are supported.

57. <see> example

58. <see> output

59. <para>
•
A paragraph within other text.
•
Usually appears in the <remarks> tag.

60. <para> example

61. <para> output

62. <list>
•
A list of items
•
List item styles: table, bulleted, numbered
•
Usually appears in the remarks tag.

63. <list> example

64. <list> output

65. Building Help Files
•
GhostDoc
•
Sandcastle Help File Builder

66. Questions?