Visual Basic 1002005 [A Developers Notebook] [Electronic resources] نسخه متنی

1.10. Create XML Documentation for Your Code

Properly commenting and documenting
code takes time. Unfortunately, there's no easy way
to leverage the descriptive comments you place in your code when it
comes time to produce more detailed API references and documentation.
Instead, you typically must create these documents from scratch.

Note: Use XML comments to effortlessly create detailed code
references,a feature C# programmers have had since . NET
1.0.

Visual Studio 2005 changes all this by introducing a feature
that's been taken for granted by C# programmers
since .NET 1.0XML comments. With XML comments, you comment
your code using a predefined format. Then, you can use other tools to
extract these comments and use them to build other documents. These
documents can range from help documentation to specialized code
reports (for example, a list of unresolved issues, legacy code, or
code review dates).

1.10.1. How do I do that?

XML comments are distinguished from ordinary comments by their
format. First of all, XML comments start with three apostrophes
(rather than just one). Here's an example:

''' <summary>This is the summary.</summary>

As you can see, XML comments also have another
characteristicthey use tag names. The tag identifies the type
of comment. These tags allow you to distinguish between summary
information, information about a specific method, references to other
documentation sections, and so on.

The
most commonly used XML comment tags include:

<summary>

Describes a class or another type. This is
the highest-level information for your code.

<remarks>

Allows
you to supplement the summary information. This tag is most commonly
used to give a high-level description of each type member (e.g.,
individual methods and properties).

<param>

Describes the parameters accepted by a
method. Add one <param> tag for each
parameter.

<returns>

Describes the return value of a method.

<exception>

Allows you to specify which exceptions a
class can throw.

<example>

Lets
you specify an example of how to use a method or other member.

<see>

Allows you
to create a link to another documentation element.

In addition, there are tags that are usually used just to format or
structure blocks of text. You use these tags inside the other tags.
They include:

<para>

Lets you
add structure to a tag (such as a <remarks>
tag) by separating its content into paragraphs.

<list>

Starts a
bulleted list. You must tag each individual list item with the
<item> tag.

<c>

Indicates
that text within a description should be marked as code. Use the
<code> tag to indicate multiple lines as
code.

<code>

Allows
you to embed multiple lines of code, as in an example of usage. For
example, you would commonly put a <code> tag
inside an <example> tag.

In addition, you can define custom tags that you can then use for
your own purposes.

Visual Studio helps you out by automatically adding some XML
tagsbut only when you want them. For example, consider the
code routine shown here, which tests if two files are exactly the
same using a hash code. In order to use this sample as written, you
need to import the System.IO and
System.Security.Cryptography namespaces:

Public Function TestIfTwoFilesMatch(ByVal fileA As String, _
ByVal fileB As String) As Boolean
' Create the hashing object.
Dim Hash As HashAlgorithm = HashAlgorithm.Create( )
' Calculate the hash for the first file.
Dim fsA As New FileStream(fileA, FileMode.Open)
Dim HashA( ) As Byte = Hash.ComputeHash(fsA)
fsA.Close( )
' Calculate the hash for the second file.
Dim fsB As New FileStream(fileB, FileMode.Open)
Dim HashB( ) As Byte = Hash.ComputeHash(fsB)
fsB.Close( )
' Compare the hashes.
Return (Convert.ToString(HashA) = Convert.ToString(HashB))
End Function

Now, position your cursor just before the function declaration, and
insert three apostrophes. Visual Studio will automatically add a
skeleton set of XML tags, as shown here:

''' <summary>
''' 
''' </summary>
''' <param name="fileA"></param>
''' <param name="fileB"></param>
''' <returns></returns>
''' <remarks></remarks>
Public Function TestIfTwoFilesMatch(ByVal fileA As String, _
ByVal fileB As String) As Boolean
...

Now, you simply need to fill in some sample content within the tags:

''' <summary>
''' This function tests whether two files
''' contain the exact same content.
''' </summary>
''' <param name="fileA">Contains the full path to the first file.</param>
''' <param name="fileB">Contains the full path to the second file.</param>
''' <returns>True if the files match, false if they don't.</returns>
''' <remarks>
''' The implementation of this method uses cryptographic classes
''' to compute a hash value. This may not be the most performant
''' approach, but it is sensitive to the minutest differences,
''' and can't be practically fooled.
''' </remarks>

To make a more realistic example, put the
TestIfTwoFilesMatch( ) method into a class, and
add XML documentation tags to the class declaration.
Here's a typical example, which uses
cross-references that point to the available methods in a list:

''' <summary>
''' This class contains methods for comparing files.
''' </summary>
''' <remarks>
'''        <para>This class is stateless. However, it's not safe to use
''' it if the file in question may already be help open by another
''' process.</para>
'''        <para>The methods in this class include:</para>
'''        <list type="bullet">
'''            <item><see cref="FileComparer.TestIfTwoFilesMatch"/>
''' TestifTwoFilesMatch( ) uses hash codes to compare two files.</item>
'''        </list>
''' </remarks>
Public Class FileComparer
...
End Class

Unlike other comments, XML comments are added to the metadata of your
compiled assembly. They'll automatically appear in
the Object Browser when you examine a type.

Additionally, once you've created your XML tags, you
can export them to an XML document. Just double-click the My Project
node in the Solution Explorer, choose the Compile
tab, and ensure that the "Generate XML documentation
file" option is selected. The XML documentation is
automatically saved into an XML file with the same name as your
project and the extension .xml (in the
bin directory).

The generated document will include all of the XML comments, with
none of the code. You can then feed this document into some other
type of application. For example, you might create your own custom
application to scan XML comment files and build specialized reports.

1.10.2. What about...

...creating help documentation?
Although Visual Studio 2005 doesn't include any
tools of its own, the open source NDoc application provides a
solution (http://ndoc.sourceforge.net). NDoc scans code
and uses the XML documentation tags it finds to build MSDN-style web
pages or Visual Studio-style (MS Help 2.0) documentation. At the time
of this writing, NDoc doesn't yet support .NET 2.0.

1.10.3. Where can I learn more?

The MSDN reference has much more information about XML comments,
including guidelines for how to document types and how to use the
standard set of tags. Look for the "XML
documentation" index entry.