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?