VSdocman provides a mechanism for developers to document their code using XML. In source code files, lines that begin with ''' in VB or /// in C# (or other user defined prefix) and that precede a user-defined type such as a class, delegate, or interface; a member such as a field, event, property, or method; or a namespace declaration can be processed as comments and placed in a file.

Example

The following sample provides a basic overview of a type that has been documented.

Visual Basic

Copy CodeCopy Code

'''<summary> The main class of TestDll.</summary>

'''<remarks>Here we show how to use XML comments.</remarks>

Public Class DllClass1

 

   '''<summary>Our sample property.</summary>

   '''<remarks>This property is really interesting.</remarks>

   '''<value>Some nice text.</value>

   '''<example>This is an example how to use prop1 and prop2 properties.

   '''<code>

   '''   Me.prop1 = Me.prop2

   ''' </code></example>

   '''<author>Peter Macej</author>

   '''<version>3.0</version>

   '''<revision>27</revision>

   '''<includesource>yes</includesource>

   '''<copyright>(c) 2008 Helixoft</copyright>

   '''<todo>Improve exception handling</todo>

   '''<seealso cref="TestDLL.DllClass1.prop2">Another interesting

   '''property</seealso>

   Property prop1() As String

     Get

     End Get

     Set(ByVal Value As String)

     End Set

   End Property

 

   '''<summary>Sample method with two arguments.</summary>

   '''<param name="x">The first parameter.</param>

   '''<param name="y">The second parameter.</param>

   '''<returns>True if no error occurs.</returns>

   '''<exception cref="TestDLL.DllClass1.nestedException">If

   '''something horrible happens.</exception>

   Function method1(ByVal x() As Integer, ByVal y As String) As Boolean

   End Function

 

   '''<summary> This is our custom exception.</summary>

   '''<remarks>This is also an example of nested class.</remarks>

   <AttributeUsage(AttributeTargets.Class, AllowMultiple:=True)> _

   Class nestedException

     Inherits Exception

   End Class

End Class

C#

Copy CodeCopy Code

///<summary> The main class of TestDll.</summary>

///<remarks>Here we show how to use XML comments.</remarks>

public class DllClass1

{

    

    ///<summary>Our sample property.</summary>

    ///<remarks>This property is really interesting.</remarks>

    ///<value>Some nice text.</value>

    ///<example>This is an example how to use prop1 and prop2 properties.

    ///<code>

    ///   Me.prop1 = Me.prop2

    /// </code></example>

    ///<author>Peter Macej</author>

    ///<version>3.0</version>

    ///<revision>27</revision>

    ///<includesource>yes</includesource>

    ///<copyright>(c) 2008 Helixoft</copyright>

    ///<todo>Improve exception handling</todo>

    ///<seealso cref="TestDLL.DllClass1.prop2">Another interesting

    ///property</seealso>

    public string prop1 {

        get { }

        set { }

    }

    

    ///<summary>Sample method with two arguments.</summary>

    ///<param name="x">The first parameter.</param>

    ///<param name="y">The second parameter.</param>

    ///<returns>True if no error occurs.</returns>

    ///<exception cref="TestDLL.DllClass1.nestedException">If

    ///something horrible happens.</exception>

    public bool method1(int[] x, string y)

    {

    }

    

    ///<summary> This is our custom exception.</summary>

    ///<remarks>This is also an example of nested class.</remarks>

    [AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]

    public class nestedException : Exception

    {

    }

}

 

Code Discussion

XML documentation starts with ''', /// or other user defined prefix. The processing of these comments has some restrictions:

•The documentation must be well-formed XML. If the XML is not well-formed, VSdocman may generate incorrect output. You can easily test your comments by launching comment editor. If everything looks fine in editor, it should look fine in the final documentation as well.

•Developers are free to create their own set of tags. There is a built-in set of tags (see Comment Tags).

Note

Remember that XML comments must be well-formed XML. Therefore some characters cannot be used in attribute or tag value. Those characters often appear in the source code so you have to be careful especially when using <code> or <c> tags. You must escape the following characters:

Character

Escape sequence

quote (")

&quot;

apostrophe (')

&apos;

ampersand (&)

&amp;

less than (<)

&lt;

greater than (>)

&gt;

The safest way to enter these characters is to use VSdocman WYSIWYG comment editor.

See Also