NDoc User's Guide NDoc 1.3

Decorating Your Code

[This is preliminary documentation and subject to change]

The more, the better

The more code comments you add to your code, the more descriptive the generated help topics will be. That makes your help file more useful to the users of your assemblies.

At a minimum each public type, and the public and protected members of your public types, should have a <summary> item describing what the member does or represents.

The VS.NET C# code editor has a handy feature that makes it easy to create the basic code comments for each type and member:

For the following code snippet:

public class MyClass() {
public MyClass( string s ) { }
}

if you place your cursor just above the MyClass constructor, and hit the '/' character three times in a row, VS.NET will create the skeleton of a code comment block for that member:

public class MyClass() {
/// <summary>
///
/// </summary>
/// <param name="s"></param>
public MyClass( string s ) { }
}

This applies to any type or member that can have code comment tags associated with it. Further more, once you have a code comment block, when you hit the '<' key to start a new tag, VS.NET will display an intellisense selector showing the appropriate list of code comment tags. Unfortunately this list won't include the additional tags that NDoc supports, but you can still add them by hand.

NDoc includes options that allow you to generate documentation for private and internal items. This is useful when you are using NDoc to generate in-house documentation. If you plan to use NDoc in this way you should also add code comments to types and members that would not normally be visible outside of the assembly.