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.

  ' TestDLL.vb
  '''<summary> The main class of TestDll.</summary>
  '''<remarks>Here we show how to use VSdocman 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) 2006 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
   

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).

See Also

Adding Comment | Comment Tags | Comment Editor