Some Ideas about applying XML annotation tag in C #

1. Content involved:

• Visual Studio 2005 Development Environment
• Write comments in C #
• XML annotation tag in C #
• Tooltip automatic prompt in Visual Studio 2005 IDE environment

2. Problems found:

In the C # development environment of Visual Studio 2005, you can use the XML annotation mark you have written to call a function to generate automatic prompts similar to tooltip, you can prompt information about function functions and parameters.

Problem: when you use the XML annotation tag automatically generated by Visual Studio 2005 IDE, this tooltip only prompts the content under the <summary> </Summary> and <param> </param> labels (1. Figure 2 ). The content under <returns> </returns> is not displayed. In other words, I think the information provided by IDE is not rich enough. I want it to prompt more information and make the layout clear and beautiful.

Figure 1

Figure 2

Corresponding XML comment:

XML annotations for Figure 1 and figure 2Code
/// <Summary>
/// Write the attribute information to the database.
/// </Summary>
/// <Param name = "toolattributewithvalue"> A toolattributewithvalue array containing attributes and attribute values. </Param>
/// <Returns> success-true; failure-False. </Returns>
Public static bool writeattribute (toolattributewithvalue [] toolattributewithvalue)

3. Implementation results

• Function prompt
• Function parameters must be prompted.
• Function return value prompt
• Branch display with different information (typographical)
• Figure 3 shows the desired effect.

 
Figure 3

Corresponding XML annotation code:

Figure 3 corresponding XML annotation code
/// <Summary>
/// Function: Write attribute information to the database. <Para/>
/// <Param name = "toolattributewithvalue">
/// Parameter: A toolattributewithvalue array containing attributes and attribute values. <Para/> </param>
/// <Returns>
/// Return: Success-true; failure-False. </Returns>
/// </Summary>
Public static bool writeattribute (toolattributewithvalue [] toolattributewithvalue)

4. Implementation Method:

When you add tooltip to the function return value, the following message is displayed:

By default, <summary> <param> <returns> are three independent tag pairs. In this case, when you point to the function name in the IDE, The tooltip only contains the content under the <summary> label, that is, neither the parameter nor the returned result will be prompted. So here we need to adjust the order of XML annotation tags. Make <param> <returns> A child element of <summary>. The corresponding XML annotation code is as follows:

Adjusted the XML annotation code after the tag order
/// <Summary>
/// Function: Write attribute information to the database.
/// <Param name = "toolattributewithvalue"> parameter: A toolattributewithvalue array containing attributes and attribute values. </Param>
/// <Returns> return value: Success-true; failure-False. </Returns>
/// </Summary>

Function functions, parameters, and return values can be displayed here, but they are displayed in one row without any branch, that is, no typographical effect. The following figure shows the branch effect. Here, an HTML Tag is used, <para/>. It is reasonable to say that <br/> is more suitable here, But I can use <br/> instead of achieving the branch effect. <para/>. For the XML annotation code, if:

Complete XML annotation code
/// <Summary>
/// Function: Write attribute information to the database. <Para/>
///
/// <Param name = "toolattributewithvalue">
/// Parameter: A toolattributewithvalue array containing attributes and attribute values. <Para/> </param>
/// <Returns>
/// Return: Success-true; failure-False. </Returns>
/// </Summary>

5. Possible problems:

We will not discuss how to use Visual Studio 2005 to extract XML comments and generate XML documents. This article adjusts the inclusion sequence of the <summary>, <param>, and <returns> tags, which may affect the generated XML document. I did not verify this problem because I will not generate XML documents with Visual Studio 2005.

This is the first article written in "blog Garden". This function can insert code blocks is really great!