Use XML annotations in. Net (1)-XML annotation labels

From: http://www.cnblogs.com/zhangziqiu/archive/2009/01/23/xmlcomment.html

I. Summary

. Net allows developersSource codeInsert XML annotations, which is particularly useful for collaborative development by multiple people. C # The parser canCodeThe XML tags in the file are extracted and further processed as external documents. This articleArticleIt will show you how to use these XML annotations. Many people are reluctant to write complicated documents during project development. However, the development team lead wants the code comments to be as detailed as possible; The project planner wants the code design documents to be as detailed as possible; the testers want the functional manuals to be as detailed as possible. If these documents are required to be written, it is more painful to keep them synchronized than to conduct a battle.

Why not store the information in one place ?? The most obvious thing to think of is in the comments of the Code.ProgramAnd some people who need these documents do not understand coding. The best solution is to solve these problems by using XML annotations. Code comments, user manuals, developer manuals, and test plans can be easily obtained from XML comments. This article explains how.. net. C # Language J ,. other languages supported by the. NET platform use the same XML annotation format. in the next section of this series of articles, I will explain how to use tools to convert XML comments into help documents.

Ii. xml comment Overview

All XML comments follow three forward slashes (///). The two diagonal lines indicate a comment, and the compiler ignores the subsequent content. The three diagonal lines tell the compiler that XML comments are followed and need to be processed properly.

After a developer enters three forward slashes, Microsoft Visual Studio. Net ide automatically checks whether the dash is in front of the definition of a class or class member. If yes, Visual Studio. Net ide will automatically insert annotation tags, and developers only need to add some additional tags and values. The following is a comment that is automatically added by adding three diagonal lines before the member function:

 
/// <Summary> /// obtain the hotel information of the specified hotel // </Summary> /// <Param name = "Relative ID"> hotel id </param>/ // <Param name = "languagecode"> language code. chinese: ZH-CN </param> /// <returns> hotel information object </returns> [operationcontract] outationinfo get1_infobyhotelid (string loginname, string loginpassword, string Region ID, string languagecode );
 

The summary, Param, and returns mark embedded here is only a part of the mark that Visual Studio can recognize. However, in Intelligent Sensing intelliisense, all the labels in the C # specification are not listed, the missing part can only be inserted manually. These manual tags are very useful. If you set them properly, it will be very helpful to export them to an external instruction file.

3. generate an XML file with the Annotation

The comments added in the code can be extracted separately to generate xml files. These XML files are used when the help files are created.

By default, the Comment XML file is not generated. Each project can generate an XML file, which needs to be set in the project properties:

As shown in, on the "property page"-> "generate" of the project, select the "XML document file" check box to generate a comment XML file during compilation. by default, the generated path is in the same folder as the DLL file, or you can modify it yourself. note that the relative path is entered here.

Iv. List of common comment labels

Annotations are easy to use, but few annotations are used. this is because the comments in most projects only serve to programmers themselves. to generate a document like msdn, we need to learn more about Annotation labels. below are some of my frequently used annotation labels:

Tag Name

Description

Syntax

Parameters

<Summary>

<Summary> the tag should be used to describe the type or type member. Use <remarks> to add additional information for a type description.

<Summary> the marked text is the only source of information about the types in intelliisense, and it is also displayed in the Object Browser.

<Summary>

Description

</Summary>

Description: The abstract of the object.

<Remarks>

Use the <remarks> flag to add information about the type to supplement the information specified by <summary>. This information is displayed in the Object Browser.

<Remarks>

Description

</Remarks>

Description: Member description.

<Param>

<Param> flag should be used in the annotation of the method declaration to describe a parameter of the method.

The text for the <param> tag is displayed in the intelliisense, object browser, and code comment Web report.

<Param name = 'name'>

Description

</Param>

Name: method parameter name. Enclose the name in double quotation marks ("").

Description: parameter description.

<Returns>

<Returns> mark the comment that should be used for method declaration to describe the return value.

<Returns>

Description

</Returns>

Description: Description of the returned value.

<Value>

<Value> flag allows you to describe the value represented by the property. Note that when you use the code Wizard to add a property in the Visual Studio. NET development environment, it adds the <summary> flag for the new property. Then, you should manually add the <value> flag to describe the value represented by this attribute.

<Value>

Property-Description

</Value>

Property-Description: description of the property

<Example>

Use the <example> flag to specify the usage method or examples of other library members. This usually involves using the <code> flag.

<Example>

Description

</Example>

Description: A description of the sample code.

<C>

<C> flag provides a method to mark the text in the description as code. Use <code> to indicate multiple lines as code.

<C>

Text

</C>

Text: indicates the text of the Code.

<Code>

Use the <code> flag to indicate multiple lines as code. Use the <C> instruction to mark the text in the description as code.

<Code>

Content

</Code>

Content: The text that you want to mark as code.

<Exception>

<Exception> flag allows you to specify which exceptions can be thrown. This tag can be used in the definition of methods, properties, events, and indexers.

<Exception

Cref = "member">

Description

</Exception>

Cref:

References to exceptions that can be obtained from the current compilation environment. After the compiler checks that a given exception exists, it converts member to the canonicalized element name in the output XML. Member must be enclosed in double quotation marks.

For more information about how to create a CREF reference to a generic type, see <see>

Description: exception description.

<See>

<Seealso>

<See> the tag allows you to specify links from the text. Use <seealso> to indicate that the text should be placed in the "See also" section.

<See CREF = "member"/>

Cref:

References to members or fields that can be called through the current compilation environment. The compiler checks whether the given code element exists and passes the Member to the element name in the output XML. Member should be placed in double quotation marks.

<Para>

The <para> tag is used in a tag such as <summary>, <remarks>, or <returns> to add the structure to the text.

<Para> content </para>

Content: paragraph text.

<Code> *

Provides a method to insert code.

<Code src = "src" Language = "Lan" encoding = "C"/>

SRC: Location of the Code File

Language: computer language of the Code

Encoding: file encoding

*

Used to insert images into a document

SRC: The image location, relative to the XML file where the comment is located

<File> *

Used to insert a file in the document. The file is displayed as a download link on the page.

<File src = "src"/>

SRC: file location, relative to the XML file where the comment is located

<Localize> *

Provides a method for annotation localization. child nodes with different names than the current thread language will be ignored.

<Localize>

<ZH-CHS> Chinese </ZH-CHS>

<En> English </en>

...

</Localize>

5. Notes and help documents

The ultimate goal of improving the annotation information is to generate a program help document like msdn, which will be used by various roles throughout the project lifecycle: developers maintain the program through this document, the tester uses this document to understand the business logic, and the Project Manager uses this document as a project description.

Therefore, to understand the functions of these uncommon comments in the list, it is necessary to associate them with the final help document. the following example illustrates the role of the annotation tag in the Help file. the next article in this series describes how to generate a Help file.

First, let's take a look at the Help file. We have read the msdn help document. The suffix of the Help file generated by using the annotation XML file is CHM, which is basically the same as that of msdn after it is opened:

The namespace in this example is xmlcommentclassdemo, which contains two classes:

Userbl is a class that contains methods.

Userinfo is a model class with only two attributes: userid and username.

(1) Class Annotation

Let's take a look at the annotation code of the userbl class:

 
/// <Summary> /// user object business logic layer. /// </Summary> /// <remarks> /// 2009.01.01: create. ziqiu. zhang <br/> // 2009.01.23: added the GetUserName and getuserid methods. ziqiu. zhang <br/> /// </remarks> public class userbl {...}
 

The content of the summary tag is displayed in the namespace class list. For example, the content of the. Remarks tag is displayed on the class page, for example:

Compared with the previous annotations, the following annotations are the annotations that need to be added to the header when creating a new file:

/*************************************** **************************************** * *********** File Name: optional commentheaderinfo. CS ** Creator: Ziqiu. zhang ** create time: 2008-09-17 ** Functional Description: Model of the hotel's comment header. This includes the comment header corresponding to the Hotel entity, the hotel outputted info information *, and the tag information set of the hotel entity. ** Remark: *** copyright (c) elong Corporation. all rights reserved. **************************************** **************************************** ********/
 

The purpose of adding this comment block is good. but it is difficult to promote. this annotation cannot be recognized by the compiler or added to the annotation XML file to generate a Help file. the format is not easy to remember. When you want to add a file, you can only copy it from another file and modify it. the company lacks a complete code review mechanism, so many files do not have this comment block.

Compared with the. NET annotation language, it is not only "agile", but also a description in the Help file.

(2) method Annotation

Class annotations are relatively simple. To style the effect of commonly used annotation labels, I used as many annotation labels as possible in method annotations. The Code is as follows:

/// <Summary> /// obtain the user name based on the user ID. /// <para> // Add the second summary information here, which is rarely used in msdn. therefore, it is not recommended. /// </para> /// </Summary> /// <remarks> /// if no user is found, null is returned. <br/> /// <paramref name = "userid"/> the parameter is a positive integer. <br/> // For the definition of user ID model attributes, see <see CREF = "userinfo. userid "/> <br/> // related method: <seealso CREF =" userbl. getuserid "/> /// </remarks> // <Param name =" userid "> User ID </param> /// <returns> real user name </returns> /// <example> /// returns the 100 user ID Real User name: // <code> // Private string username = string. empty; // username = userbl. getUserName (100); /// </code> // The returned username may be null. You must first judge it when using it: <br/> // <C> If (username! = NULL ){...} </C> /// </example> /// <exception CREF = "system. applicationexception "> // this exception is thrown if the user ID is smaller than 0 // </exception> Public static string GetUserName (long userid) {string result = string. empty; If (userid <0) {Throw new system. applicationexception ();} else if (userid = 0) {result = NULL;} else {result = "Robert";} return result ;}

Next, let's explain in detail through the image. First, when viewing class members:

After clicking the method:

Notes:

1) The seealso tag is added to the remarks tag at the beginning, so no method connection is added to the see also region. The solution is to put the seealso tag in the summary tag.

2) The CREF attribute of the exception class must be set to a class that can be recognized by the compiler so that you can click it in the help document. for example, the above system. applicationexception click to go to Microsoft's online msdn query. if the exception is defined by yourself, this exception class is also required in your help file. comments to XML and dependent DLL are generally provided.

(3) attribute comments

The annotation of the attribute is also very simple. Unlike the class, the attribute must be described using the <value> label rather than the <remarks>:

 
Private string m_username = string. empty; // <summary> // real user name // </Summary> // <value> string of the user's real name. the default value is null. </value> Public String username {get {return m_username;} set {m_username = value ;}}
 

Effect:

Vi. Summary

This article explains the XML annotation tag in. NET and Its Role in the help document.

understand how to use tags. In the next article, we will show you how to use tools to generate the Help file in this example.