Comments

Links

XML Comments Let You Build Documentation Directly From Your Visual Studio .NET Source Files.

GhostDoc

http://www.roland-weigelt.de/ghostdoc/

Download and install GhostDoc…

To assign a keyboard mapping:

Tools, Options, then select Environment, Keyboard.
To find the command, type “ghost” in the “show commands containing” input field and you’ll see two commands. Select the “DocumentThis” command.
Open the “Use new shortcut in” drop down list and pick “Text Editor”.
```
../../images/howto/csharp/ghostdoc-keyboard-mapping.gif
```
Now choose a hotkey (I used the normal JavaDoc keys, Shift, Alt, J), and press Assign.
```
../../images/howto/csharp/ghostdoc-keyboard-mapping-2.gif
```

To create documentation for a method, move the cursor to the method and press your hotkey.

XML Comments

All XML comments begin with three forward slashes (///). The first two slashes signify a comment and tell the compiler to ignore the text that follows. The third slash tells the parser that this is an XML comment and should be handled appropriately.

When the developer types the three forward slashes, the Microsoft Visual Studio .NET IDE checks to see if it precedes an identifiable type or type member definition. If it is identifiable, then the Visual Studio .NET IDE will automatically insert a few comment tags.

Summary

/// <summary>
/// Calling this function will take the XML in <see cref="SourceXML"/>
/// and translate it to a list of Members in the specified type.
/// </summary>
/// <param name="strType">The fully qualified name of the type that the member is in.</param>
/// <returns>The HTML that lists the types that are in the XML documentation.</returns>
/// <seealso cref="GiveTypeListHTMLHelp"/>
/// <seealso cref="GiveMemberHTMLHelp"/>
/// <example><code>
/// // create the class that does translations
/// GiveHelpTransforms ght = new GiveHelpTransforms();
/// </code></example>
/// <permission cref="">public</permission>
public string GiveMemberListHTMLHelp(string strType)
{

Code

The <c> tag marks a line of text as code. It is usually used inline in descriptive text:

/// The source XML is loaded into the <see cref="SourceXML"/>
/// property (e.g. <c><I>obj</I>.SourceXML =
/// "<I>XML goes here</I>"</c>).

The <code> tag also defines a section of text as code. It is often used within an <example> tag block (as shown earlier). The <code> tag is similar to the <c> tag, but <c> is used for a single line of code while <code> is used for a block of code:

/// <code>
/// ght.LoadXMLFromFile("GiveHelpDoc.xml");
/// </code>

Exceptions

/// <exception cref="SampleException">
/// Normally, a discussion on any exceptions thrown would go here.
/// </exception>

Inheritance

From Document Your Code in No Time At All with Macros in Visual Studio:

…one of the greatest stumbling blocks in achieving comprehensive documentation coverage of your code - the absence of a “documentation inheritance” feature in Visual Studio.

Links

/// Initializes a new instance of the <see cref="Helper"/> class.

/// <see href="http://weezy/svn/projects/sample-app/"/>

List

http://www.softsteel.co.uk/tutorials/cSharp/lesson19.html

Bullet

<list type="bullet">
  <item>
    Apple
  </item>
  <item>
    Cheese
  </item>
</list>

…can also use a list type of “number”.

Table

<list type="table">
  <listheader>
    <term>Animal</term>
    <description>Type</description>
  </listheader>
  <item>
    <term>monkey</term>
    <description>hairy</description>
  </item>
  <item>
    <term>pig</term>
    <description>bald</description>
  </item>
</list>

Paragraph

/// <para>This is a new paragraph.</para>