第 36 页

/// <item>

/// <term>Not Complex</term>

/// <description>The new password did not meet the complexity requirements. It

/// must contain at least one of the following characters: lowercase, uppercase,

/// and number.

/// </description>

/// </item>

/// </list>

/// </summary>

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

Vb

''' <summary>

''' This function changes a users password. The password change could fail for

''' several reasons:

''' <list type="bullet">

''' <item>

228 .

chaPter 12 documenTATion WiTh xml commenTS

''' <term>Too Short</term>

''' <description>The new password was not long enough.</description>

''' </item>

''' <item>

''' <term>Not Complex</term>

''' <description>The new password did not meet the complexity requirements. It

''' must contain at least one of the following characters: lowercase, uppercase,

''' and number.

''' </description>

''' </item>

''' </list>

''' </summary>

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

'...code...

Return True

End Function

The <para> Tag

Without using the various internal block-level XML comments such as <list> and <code>, the

text you add to the main <summary>, <remarks>, and <returns> sections all just runs together.

To break it up into readable chunks, you can use the <para> tag, which simply indicates that the

text enclosed should be treated as a discrete paragraph. The syntax is simple:

<para>This text will appear in a separate paragraph.</para>

The <param> Tag

To explain the purpose of any parameters in a function declaration, you can use the <param>

tag. This tag will be processed by the Visual Studio XML comment processor with each instance

requiring a name attribute that has a value equal to the name of one of the properties. Enclosed

between the opening and closing <param> tag is the description of the parameter:

<param name="parameterName">Definition of parameter.</param>

The XML processor will not allow you to create multiple <param> tags for the one parameter, or

tags for parameters that don’t exist, producing warnings that are added to the Error List in Visual

Studio if you try. The following example shows how the <param> tag is used to describe two

parameters of a function:

c#

/// <param name="oldPwd">Old password-must match the current password</param>

/// <param name="newPwd">New password-must meet the complexity requirements</param>

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

XMl Comments .

229

Vb

''' < param name="oldPwd" > Old password-must match the current password < /param >

''' < param name="newPwd" > New password-must meet the complexity requirements < /param >

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

'...code...

Return True

End Function

The < param > tag is especially useful for documenting preconditions for a

method’s parameters, such as if a null value is not allowed.

The <paramref> Tag

If you are referring to the parameters of the method definition elsewhere in the documentation

other than the < param > tag, you can use the < paramref > tag to format the value, or even link to

the parameter information depending on how you code the XML transformation. The compiler

does not require that the name of the parameter exist, but you must specify the text to be used in

the name attribute, as the following syntax shows:

< paramref name="parameterName" / >

Normally, < paramref > tags are used when you are referring to parameters in the larger sections of

documentation such as the < summary > or < remarks > tags, as the following example demonstrates:

c#

/// < summary >

/// This function changes a users password. This will throw an exception if

/// < paramref name="oldPwd" / > or < paramref name="newPwd" / > are nothing.

/// < /summary >

/// < param name="oldPwd" > Old password-must match the current password < /param >

/// < param name="newPwd" > New password-must meet the complexity requirements < /param >

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

Vb

''' < summary >

''' This function changes a users password. This will throw an exception if

''' < paramref name="oldPwd" / > or < paramref name="newPwd" / > are nothing.

''' < /summary >

''' < param name="oldPwd" > Old password-must match the current password < /param >

''' < param name="newPwd" > New password-must meet the complexity requirements < /param >

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

230 .

chaPter 12 documenTATion WiTh xml commenTS

'...code...

Return True

End Function

The <permission> Tag

To describe the code access security permission set required by a particular method, use the

<permission> tag. This tag requires a cref attribute to refer to a specific permission type:

<permission cref="permissionName">

description goes here

</permission>

If the function requires more than one permission, use multiple <permission> blocks, as shown in

the following example:

c#

/// <permission cref="System.Security.Permissions.RegistryPermission">

/// Needs full access to the Windows Registry.

/// </permission>

/// <permission cref="System.Security.Permissions.FileIOPermission">

/// Needs full access to the .config file containing application information.

/// </permission>

public string UserId { get; set; }

Vb

''' <permission cref="System.Security.Permissions.RegistryPermission">

''' Needs full access to the Windows Registry.

''' </permission>

''' <permission cref="System.Security.Permissions.FileIOPermission">

''' Needs full access to the .config file containing application information.

''' </permission>

Public Property UserId() As String

The <remarks> Tag

The <remarks> tag is used to add an additional comment block to the documentation associated

with a particular method. Discussion on previous tags has shown the <remarks> tag in action, but

the syntax is as follows:

<remarks>

Any further remarks go here

</remarks>

Normally, you would create a summary section, briefly outline the method or type, and then

include the detailed information inside the <remarks> tag, with the expected outcomes of

accessing the member.

XMl Comments .

231

The <returns> Tag

When a method returns a value to the calling code, you can use the < returns > tag to describe what

it could be. The syntax of < returns > is like most of the other block-level tags, consisting of an

opening and closing tag with any information detailing the return value enclosed within:

< returns >

Description of the return value.

< /returns >

A simple implementation of < returns > might appear like the following code:

c#

/// < summary >

/// This function changes a user’s password.

/// < /summary >

/// < returns >

/// This function returns:

/// < c > True < /c > which indicates that the password was changed successfully,

/// or < c > False < /c > which indicates that the password change failed.

/// < /returns >

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

Vb

''' < summary >

''' This function changes a user’s password.

''' < /summary >

''' < returns >

''' This function returns:

''' < c > True < /c > which indicates that the password was changed successfully,

''' or < c > False < /c > which indicates that the password change failed.

''' < /returns >

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

'...code...

Return True

End Function

In addition to return value of a function, the < returns > tag is especially useful

for documenting any post-conditions that should be expected.

232 .

chaPter 12 documenTATion WiTh xml commenTS

The <see> Tag

You can add references to other items in the project using the < see > tag. Like some of the other tags

already discussed, the < see > tag requires a cref attribute with a value equal to an existing member,

whether it is a property, method, or class definition. The < see > tag is used inline with other areas of

the documentation such as < summary > or < remarks > . The syntax is as follows:

< see cref="memberName" / >

When Visual Studio processes the < see > tag it produces a fully qualified address that can then be

used as the basis for a link in the documentation when transformed via style sheets. For example,

referring to an application with a class containing a function named ChangePwd would result in the

following cref value:

< see cref="applicationName.className.ChangePwd"/ >

The following example uses the < see > tag to provide a link to another function called CheckUser:

c#

/// < remarks >

/// Use < see cref="CheckUser" / > to verify that the user exists before calling

/// ChangePwd.

/// < /remarks >

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

Vb

''' < remarks >

''' Use < see cref="CheckUser" / > to verify that the user exists before calling

''' ChangePwd.

''' < /remarks >

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

'...code...

Return True

End Function

In VB only, if the member specified in the cref value does not exist, Visual

Studio will use IntelliSense to display a warning and add it to the Error List.

The <seealso> Tag

The < seealso > tag is used to generate a separate section containing information about related topics

within the documentation. Rather than being inline like < see > , the < seealso > tags are defined

XMl Comments .

233

outside the other XML comment blocks, with each instance of <seealso> requiring a cref attribute

containing the name of the property, method, or class to which to link. The full syntax appears like so:

<seealso cref="memberName" />

Modifying the previous example, the following code shows how the <seealso> tag can be

implemented in code:

c#

/// <remarks>

/// Use <see cref="CheckUser" /> to verify that the user exists before calling

/// ChangePwd.

/// </remarks>

/// <seealso cref="ResetPwd" />

public bool ChangePwd(string oldPwd, string newPwd)

{

//...code...

return true;

}

Vb

''' <remarks>

''' Use <see cref="CheckUser" /> to verify that the user exists before calling

''' ChangePwd.

''' </remarks>

''' <seealso cref="ResetPwd" />

Public Function ChangePwd(ByVal oldPwd As String, ByVal newPwd As String) _

As Boolean

'...code...

Return True

End Function

The <summary> Tag

The <summary> tag is used to provide the brief description that appears at the top of a specific topic

in the documentation. As such it is typically placed before all public and protected methods and

classes. In addition, the <summary> area is used for Visual Studio’s IntelliSense engine when using

your own custom-built code. The syntax to implement <summary> is as follows:

<summary>

A description of the function or property goes here.

</summary>

The <typeparam> Tag

The <typeparam> tag provides information about the type parameters when dealing with a generic

type or member definition. The <typeparam> tag expects an attribute of name containing the type

parameter being referred to:

<typeparam name="typeName">

Description goes here.

</typeparam>

234 .

chaPter 12 documenTATion WiTh xml commenTS

You can use <typeparam> in either C# or VB, as the following code shows:

c#

/// <typeparam name="T">

/// Base item type (must implement IComparable)

/// </typeparam>

public class myList<T> where T : IComparable

{

//...code...

}

Vb