NET specification Note (i)--XML comment tag explanation

I. Summary

. NET allows developers to insert XML annotations into their source code, which is especially useful when collaborating with multiple developers. The C # parser can extract these XML tags from the code file and make further processing as an external document. This article will show you how to use these XML annotations. In project development, many people are not happy to write complex documents. However, the development leader wants the code comment to be as detailed as possible, and the project planner wants the code design document to be as detailed as possible; If these documents are required to be written, it is more painful to keep them synchronized than to carry out a battle.

Why not keep this information in one place?? The most obvious place to think about is the comments in the code, but it's hard to browse through the program, and some people who need those documents don't know the coding. The best approach is to solve these problems by using XML annotations. Many documents, such as code comments, user manuals, developer manuals, test plans, and so on, can be easily obtained from XML annotations. This article explains. The XML annotations that are frequently used in net. The main use of C # language J,. The XML annotation format used by other languages supported by the net platform is basically the same. And in the next lecture in this series, we'll explain how to use tools to translate XML comment content into a help document.

Two. XML Annotations overview

All XML annotations are preceded by a three forward slash (//). A two slash indicates a comment, and the compiler ignores the following. The three slash tells the compiler, followed by an XML comment, that needs to be handled appropriately.

When a developer enters three forward slashes, the Microsoft Visual Studio. NET IDE automatically checks to see if it precedes the definition of a class or class member. If so, the Visual Studio. NET IDE will automatically insert comment tags, and developers will only need to add additional tags and values. The following is an increment of three diagonal lines before the member function, which automatically adds annotations such as:

        <summary>///        receive hotel information for designated hotels///</summary>//                <param name= "Hotelid" > Hotel id</param>///        <param name= "Languagecode" > Language code. Chinese to zh-cn</param>//        < Returns> Hotel Information Objects </returns> [OperationContract] outhotelinfo gethotelinfobyhotelid (string languagecode) ;

The summary,param,returns tag embedded here is only part of the markup that Visual Studio recognizes, but in IntelliSense, it does not list all the tags in the C # specification, and the missing parts can only be inserted manually. These manual tags are very useful, and if they are set appropriately, it will be helpful to export them as external documentation.

Three. Generate an XML file for annotations

The comment information that is added in the code can be extracted separately to generate an XML file. These annotation XML files are used when making the final help file.

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

As shown, in the project's property pages, build, tick the XML document file check box to generate a comment XML file at compile time. The build path defaults to the same folder as the DLL file and can be modified by itself. Note the relative path is filled in here.

Four. List of common comment tags

The use of annotations is simple, but the annotations we use are very few. This is because the annotations in most projects are only for the programmer to see for themselves. If you want to generate a document like MSDN, we need to know more about the comment tags. Here are the common comment tags I've compiled:

Label name	Description	Grammar	Parameters
<summary>	<summary >  tag should be used to describe a type or type member. Use  <remarks>  <summary>  The tagged text is the only relevant  intellisense	<summary> description </summary>	description:
<remarks>	use  < Span lang= "en-US" ><remarks> <summary>   Specifies the information. This information is displayed in the Object Browser.	<remarks> description </remarks>	description: description of the member.
<param>	<param>   tag should be used in the comments of the method declaration to describe one of the parameters of the method. about  <param>  Tagged text will be displayed in  intellisense web  in the report.	<paramname= ' name '; description </param>	name: method parameter name. Enclose this name in double quotation marks   ("") description: parameter description.
<returns>	<returns >  tag should be used for comments on the method declaration to describe the return value.	<returns> description </returns>	description: A description of the return value.
<value>	<value>   tag allows you to describe the value that the property represents. Note that when you add a property through the Code wizard in the  visual Studio. Net  development environment, it will add a new property  <summary>  tags. Then, you should manually add the  <value>	<value> property-description </value>	property-description:
<example>	use  <example>  tag can specify examples that use methods or other library members. This usually involves the use of  <code>  tags.	<example> description </example>	description:  A description of the code sample.
<c>	The <c> tag gives you a way to mark the text in the description as code. Use <code> to indicate multiple lines as code.	<c> Text </c>	text: A literal that you want to indicate as code.
<code>	Use the <code> tag to indicate multiple lines as code. Use <c> to indicate that the text in the description should be marked as code.	<code> Content </code>	Content: The text that you want to mark as code.
<exception>	The <exception> tag allows you to specify which exceptions can be raised. This tag can be used in the definition of methods, properties, events, and indexers.	<exception cref= "Member" > Description </exception>	cref:  member  xml   member   ("")    <see> description: description of the exception.
<see> <seealso>	<see>  tags allow you to specify links from within the text. Use  <seealso>	<seecref= "member"/>	cref:  member  xml   member   ("")
<para>	<para>   tag for such <summary>,< Remarks>  <returns>	<para>content</ Para>	content: paragraph text.
<code>*	Provides a way to insert code.	<code src= "src" language= "LAN" encoding= "C"/>	SRC: location of code files Language: The computer language of the Code Encoding: encoding of the file
*	To insert a picture in a document		SRC: The position of the picture, relative to the XML file where the comment is located
<file>*	To insert a file into a document and to display it as a download link in the page	<filesrc= "src"/>	SRC: The location of the file relative to the XML file where the comment is located
<localize>*	Provides a way to annotate a localized child node that has a different name than the current thread language will be ignored	<localize> <zh-chs> Chinese </zh-chs> <en>English</en> ... </localize>

Five. Comments and help documents

The ultimate goal of perfecting the annotation information is to generate the MSDN-like program Help documentation that will be used by various roles throughout the project's life cycle: Through this document maintenance program, the tester understands the business logic through this document, and the project manager uses this document as a project description and so on.

So to understand what these unusual comments do in the list, it's important to associate them with the final help document. The following example explains the role of the comment tag in the Help file. The next article in this series explains how to generate the Help file.

Let's take a look at the help file. We've all seen the MSDN Help documentation, and the Help file suffix that was generated with the comment XML file is a CHM, which is basically the same as MSDN when opened:

The namespace for this example is Xmlcommentclassdemo, which contains two classes:

USERBL is a class that contains methods.

UserInfo is a model class. There are only UserID and username two attributes.

(1) Class comment

Take a look at the comment code for the USERBL class:

    <summary>///    User Object business logic layer.    // </summary>    // <remarks>    ///2009.01.01: Create. Ziqiu.zhang <br/>    class Userbl {...}    

The contents of the summary tag are displayed in a list of namespace classes, such as the contents of the. Remarks tag in the class page, such as:

In contrast to the previous annotation specification, the following note is a note that we specify to be added to the head when creating a new file:

/*************************************************************************************** * * * *         File Name        : HotelCommentHeaderInfo.cs * *        Creator            : Ziqiu.zhang * *        Create time        : 2008-09-17 * * Functional Description: Hotel reviews head model. including the hotel entity corresponding to the reviews head, Hotel Outhotelinfo Information *, the hotel entity tag information collection.  * * * ***************************************************************************************/ 

The purpose of adding this comment block is good. But it's hard to generalize. Because this comment is not recognized by the compiler and cannot be added to the comment XML file for generating Help files. The format is not easy to remember, when you want to add it can only be copied from the other after the modification. The company lacks a perfect code review mechanism so the last many files do not have this comment block.

Compared with. NET's own annotation language, not only "agile", but also as a description in the Help file.

(2) Method comments

The comments for the class are simple. To style the effects of the comment labels, I used as many comment tags as possible in the comments of the method. The code is as follows:

        <summary>Gets the user name based on the user ID.<para>The second paragraph of summary information is added here and is rarely used in MSDN. Therefore, it is not recommended.</para></summary><remarks>Returns null.<br/> if no user is found<paramref name= "userId"/> parameter is a positive integer .<br/>User ID model attribute definitions see <see cref= "Userinfo.userid"/><br/>Related methods: <seealso cref= "Userbl.getuserid"/></remarks><param name= "userId" > User id</param><returns> user's real name </returns><example>Returns the user's real name with a user ID of 100:<code>private string userName = String. Empty;UserName = userbl.getusername (100);</code>///the user name returned may be null, use the first to Judge:<br/> ///<c>if (username!=null) {...} </c> ///</example> ///<exception cref= " System.ApplicationException "> ///if the user ID is less than 0 throws this exception ///</exception> Span class= "KWRD" >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;}             

This is followed by a detailed picture. First, when you view a class member:

After clicking on the method:

A few things to note:

1) The first seealso tag was added to the remarks label, so there is no connection to the method in the see also area. The workaround is to place the seealso tag in the summary tag.

2) The cref attribute of the exception class needs to be set to a class that the compiler can recognize so that it can be clicked in the Help document. For example, the above system.applicationexception to enter Microsoft's online MSDN query. If you define an exception, This exception class is also required in your help file. It is common to provide annotation XML and dependent DLLs.

(3) Comments on attributes

The comment for the property is also simple. Unlike classes, properties are described using <value> tags instead of <remarks>:

        String. Empty;        // <summary>        /// user's real name        value;} }

Effect:

Article turned from: http://www.cnblogs.com/mq0036/p/3544264.html

NET specification Note (i)--XML comment tag explanation