Post on 18-Jul-2015
XML Comments
Comments: Why?Communicates the expected behavior of your code to other developersMakes you think about the code youre writing
XML Comments: What?An XML Comment is an XML-based documentation that precedes the block to which they referAll 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)
XML Comments vs Inline
XML Comments vs Inline
XML Comments: Why?Standardized formatExtensible (XML)Tool supportIntellisenseObject BrowserCode Comment Web Report
XML Comments: Why?Quick creation of help files/documentationGhostDocSandcastle
Documentation SectionsThe following tags correspond to the major documentation sectionsCan be applied to any type or type member
A succinct description of a type or type memberFocuses on "what", not howDisplayed by IntellisenseTemplate: The name method/property/etc [...]
exampleNot recommended
exampleRecommended
intellisense
output
Detailed information about a type or type memberSupplemental to the information in the tag (can include "how")
example
output
Specifies which exceptions a method, property, event, or indexer can throwThe cref attribute is checked by the compilerDisplayed by Intellisense (sort of)Can have multiple per type member
example
intellisense
output
Denotes a block of code that demonstrates the use of the type or type member being documented.Used in conjunction with the tag.
example
output
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.
example
output
Specifies a link to another documentation page in a "See Also" section.cref, langword, or href attributes are supported.
example
output
Member DocumentationThe following tags are applicable to specific types of type members.
Describes a methods parameter. Also applies to constructors and destructors (finalizers).The name attribute is checked by the compiler.Each tag describes one parameter.Displayed by Intellisense
example
Intellisense
output
Describes the return value of a method
example
output
Describes the value of a property (e.g. what the propertys value represents)
example
output
Formatting TagsThe following tags provide formatting instructions for rendering documentation output.Highly recommended if you're generating documentation (using a tool like Sandcastle).
Indicates that one or more words in a tags content should be interpreted as code.Should not be used for standalone blocks of code; use instead.
example
output
Denotes a section of comments that should be read as code.Typically displayed in documentation output in a monospaced font.
example
output
Indicates that a word in a comment refers to a parameter.The name attribute is checked by the compiler.
example
Describes a generic type parameter.
example
output
Identifies a word that refers to a generic type parameter.
example
output
Specifies an inline link to another piece of relevant information.cref, langword, or href attributes are supported.
example
output
A paragraph within other text.Usually appears in the tag.
example
output
A list of itemsList item styles: table, bulleted, numberedUsually appears in the remarks tag.
example
output
Building Help FilesGhostDocSandcastle Help File Builder
Questions?