NDoc is a very useful open source project that generates reference documentation from .NET assemblies and the XML documentation files generated by the C# compiler (or an add-on tool for VB.NET).

---

• NDoc 2.0
  • The tool 
  • C# Comment Tags 
    • <c> 
    • <para> 
    • <see> 
    • <code> 
    • <param> 
    • <seealso> 
    • <example> 
    • <paramref> 
    • <summary> 
    • <exception> * 
    • <permission> * 
    • <typeparam> * 
    • <include> * 
    • <remarks> 
    • <typeparamref> 
    • <list> 
    • <returns> 
    • <value> 
  • External Links 

---

The tool

NDoc generates documentation in several different formats, including:

• the MSDN-style HTML Help format (.chm)
  
• the Visual Studio .NET Help format (HTML Help 2)
  
• MSDN-online style web pages
  

Which is much better than just the XML file we get from the compiler...

Unfortunately, NDoc has not been ported to .NET 2.0 yet. Alpha test versions have been released regularly to a private mailing list, but a final release version was never created due to the sheer complexity of the task, combined with a lack of financial support by the user community, and other unrelated issues intruding upon the development process. But since August 2006 an “unofficial”, product by a single user, a ALPHA version is available.

C# Comment Tags

<c>

Description:

The text you would like to indicate as code.

Remarks:

The <c> tag gives you a way to indicate that text within a description should be marked as code. Use <code> to indicate multiple lines as code.

Exemple:

C# 

    /// DoWork is a method in the TestClass class.

    /// 

    public static void DoWork(int Int1)

    {

    }

<para>

Description:

The text of the paragraph.

Remarks:

The <para> tag is for use inside a tag, such as <summary>, <remarks>, or <returns>, and lets you add structure to the text.

<see>

<see cref="member"/>

Parameter:: cref = " member"

A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes member to the element name in the output XML. Place member within double quotation marks (" ").

Remarks:

The <see> tag lets you specify a link from within text. Use <seealso> to indicate that text should be placed in a See Also section.

Exemple:

C#

// the following cref shows how to specify the reference, such that,

// the compiler will resolve the reference

/// <summary cref="C{T}">

/// </summary>

class A { }

// the following cref shows another way to specify the reference, 

// such that, the compiler will resolve the reference

// <summary cref="C < T >">

// the following cref shows how to hard-code the reference

/// <summary cref="T:C`1">

/// </summary>

class B { }

/// <summary cref="A">

/// </summary>

/// <typeparam name="T">

class C<T> { } 

:

<code>

Description:

The text you want marked as code.

Remarks:

The <code> tag gives you a way to indicate multiple lines as code. Use <c> to indicate that text within a description should be marked as code.

<param>

<param name='name'>description</param>

Parameters name:

The name of a method parameter. Enclose the name in double quotation marks (" ").

Description:

A description for the parameter.

Remarks:

The <param> tag should be used in the comment for a method declaration to describe one of the parameters for the method. The text for the <param> tag will be displayed in IntelliSense? , the Object Browser, and in the Code Comment Web Report.

Exemple:

C#  

/// text for class TestClass 

public class TestClass {     

   /// <param name="Int1">Used to indicate status.</param>     

   public static void DoWork(int Int1)     {     }     

   /// text for Main     

   static void Main()     {     } 

} 

<seealso>

<seealso cref="member"/>

Parameters:

A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and passes member to the element name in the output XML. must appear within double quotation marks (" ").

Remarks:

The <seealso> tag lets you specify the text that you might want to appear in a See Also section. Use to specify a link from within text.

<example>

Description:

A description of the code sample.

Remarks:

The <example> tag lets you specify an example of how to use a method or other library member. This commonly involves using the <code> tag.

Exemple:

C#

/// text for class TestClass

public class TestClass

{

    /// <summary>

    /// The GetZero method.

    /// </summary>

    /// <example> This sample shows how to call the GetZero method.

    /// <code>

    /// class TestClass 

    /// {

    ///     static int Main() 

    ///     {

    ///         return GetZero();

    ///     }

    /// }

    /// </code>

    /// </example>

    public static int GetZero()

    {

        return 0;

    }

    /// text for Main

    static void Main()

    {

    }

}

<paramref>

<paramref name="name"/>

Parameter:

The name of the parameter to refer to. Enclose the name in double quotation marks (" ").

Remarks:

The <paramref> tag gives you a way to indicate that a word in the code comments, for example in a <summary> or <remarks> block refers to a parameter. The XML file can be processed to format this word in some distinct way, such as with a bold or italic font.

<summary>

Description:

A summary of the object.

Remarks:

The <summary> tag should be used to describe a type or a type member. Use <remarks> to add supplemental information to a type description. The text for the <summary> tag is the only source of information about the type in IntelliSense? , and is also displayed in the Object Browser.

Exemple:

C#  

/// text for class TestClass

public class TestClass

{

    /// <summary>DoWork is a method in the TestClass class.

    /// <para>Here's how you could make a second paragraph in a description. 

    /// <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>

    /// <seealso cref="TestClass.Main"/>

    /// </summary>

    public static void DoWork(int Int1)

    {

    }

    /// text for Main

    static void Main()

    {

    }

}     

public static void DoWork(int Int1)     {     }      

/// text for Main     static void Main()     {     } 

} 

<exception> *

Parameter:

cref = "member"

A reference to an exception that is available from the current compilation environment. The compiler checks that the given exception exists and translates member to the canonical element name in the output XML. member must appear within double quotation marks (" ").

Description:

A description of the exception.

Remarks:

The <exception> tag lets you specify which exceptions can be thrown. This tag can be applied to definitions for methods, properties, events, and indexers.

<permission> *

Parameter:

cref = "member"

A reference to a member or field that is available to be called from the current compilation environment. The compiler checks that the given code element exists and translates member to the canonical element name in the output XML. member must appear within double quotation marks (" ").

Description:

A description of the access to the member.

Remarks:

The <permission> tag lets you document the access of a member. The PermissionSet? class lets you specify access to a member.

<typeparam> *

Description:

A description for the type parameter.

Remarks:

The <typeparam> tag should be used in the comment for a generic type or method declaration to describe a type parameter. Add a tag for each type parameter of the generic type or method.

<include> *

Parameter:

filename

The name of the file containing the documentation. The file name can be qualified with a path. Enclose filename in single quotation marks (' ').

tagpath

The path of the tags in filename that leads to the tag name. Enclose the path in single quotation marks (' ').

name

The name specifier in the tag that precedes the comments; name will have an id.

id

The ID for the tag that precedes the comments. Enclose the ID in double quotation marks (" ").

Remarks:

The <include> tag lets you refer to comments in another file that describe the types and members in your source code. This is an alternative to placing documentation comments directly in your source code file.

The <include> tag uses the XML XPath syntax. Refer to XPath documentation for ways to customize your <include> use.

Exemple:

This is a multifile example. The first file, which uses &ltinclude>, is listed below:

C#

///  &ltinclude file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test"]/*' />

class Test

{

    static void Main()

    {

    }

}

///  &ltinclude file='xml_include_tag.doc' path='MyDocs/MyMembers[@name="test2"]/*' />

class Test2

{

    public void Test()

    {

    }

}

The second file, xml_include_tag.doc, contains the following documentation comments:

<MyDocs>

  <MyMembers name="test">

    <summary>

      The summary for this type.

    </summary>

  </MyMembers>

  <MyMembers name="test2">

    <summary>

      The summary for this other type.

    </summary>

  </MyMembers>

</MyDocs>

Program Output

<doc> 

  <assembly> 

    <name>xml_include_tag</name> 

  </assembly> 

  <members> 

    <member name="T:Test"> 

      <summary> 

        The summary for this type. 

      </summary> 

    </member> 

    <member name="T:Test2"> 

      <summary> 

        The summary for this other type. 

      </summary> 

    </member> 

  </members> 

</doc> 

<remarks>

Description:

A description of the member.

Remarks:

The <remarks> tag is used to add information about a type, supplementing the information specified with <summary>. This information is displayed in the Object Browser.

Exemple:

C#

/// 

/// You may have some primary information about this class.

/// 

/// 

/// You may have some additional information about this class.

/// 

public class TestClass

{

    /// text for Main

    static void Main()

    {

    }

}

<typeparamref>

Remarks:

For more information on type parameters in generic types and methods, see Generics. Use this tag to enable consumers of the documentation file to format the word in some distinct way, for example in italics.

<list>

  <list type="bullet" | "number" | "table">

      <listheader>

          <term>term</term>

          <description>description</description>

      </listheader>

      <item>

          <term>term</term>

          <description>description</description>

      </item>

  </list>

Parameters

term

A term to define, which will be defined in description.

description

Either an item in a bullet or numbered list or the definition of a term.

Remarks:

The <listheader> block is used to define the heading row of either a table or definition list. When defining a table, you only need to supply an entry for term in the heading.

Each item in the list is specified with an <item> block. When creating a definition list, you will need to specify both term and description. However, for a table, bulleted list, or numbered list, you only need to supply an entry for description.

Exemple:

C#

/// text for class TestClass

public class TestClass

{

    ///  <summary>Here is an example of a bulleted list:

    ///  <list type="bullet">

    ///  <item>

    ///  <description>Item 1. </description>

    ///  </item>

    ///  <item>

    ///  <description>Item 2. </description>

    ///  </item>

    ///  </list>

    ///  </summary>

    static void Main()

    {

    }

}

<returns> 

Description:

A description of the return value.

Remarks:

The tag should be used in the comment for a method declaration to describe the return value.

<value>

Remarks:

The <value> tag lets you describe the value that a property represents. Note that when you add a property via code wizard in the Visual Studio .NET development environment, it will add a <summary> tag for the new property. You should then manually add a <value> tag to describe the value that the property represents.

---

* denotes that the compiler verifies syntax.

External Links

NDoc Code Documentation Generator for .NET

You can find more details about the project on the official website.

NDoc 2.0 Alpha

The web site of the developer how create the alpha version. You can also found other developer tools on that site.

XML Documentation Comments (C# Programming Guide)

MSDN Labrary the C# Programming Guide.

---

-- FrancoisBoucher - 10 May 2007