Summary of XML document comments in. net programs

 

Program annotations play a very important role in programming and maintenance ,. the XML document annotation in the Net Program increases the compilation of the program annotation to a new level: while writing the annotation, the description document is generated accordingly, this brings us great convenience. So how can I write an XML document comment? Based on my knowledge, I listed the following four points:

 

1. Compile the. Net Program XML document annotation in two formats:

L use the single line separator "//"

L use the multi-line separator "/***/"

We recommend that you use single-line delimiters to compile XML document comments.

 

2 XML Doc comments are not metadata; they are not included in the compiled assembly and therefore cannot be accessed through reflection.

 

3 The compiler will process any markup for valid XML. The following tags provide common functions in user documents:

<C>	<Para>	<See> *
<Code>	<Param> *	<Seealso> *
<Example>	<Paramref>	<Summary>
<Exception> *	<Permission> *	<Typeparam> *
<Include> *	<Remarks>	<Typeparamref>
<List>	<Returns>	<Value>

(* Indicates the compiler validation syntax .)

 

4. the compiler generates an ID string for each construction marked as a generated document in the code. The ID string uniquely identifies the structure. Programs that process XML files can use the ID string to identify the corresponding. NET Framework metadata/reflection items that the document applies. An XML file is not a hierarchical representation of code. It is a flat list and each element has a generated ID.

The compiler follows the following rules when generating an ID string:

L is not left blank in the string.

L The first part of the ID string is identified by a single character followed by a colon. Use the following member types:

Character		Description
N	Namespace Document comments cannot be added to namespaces, but they can be referenced by CREF (in a supported location ).
T	Type: Class, interface, structure, enumeration, delegate
F	Field
P	Attributes (including the Index program or other index attributes)
M	Methods (including some special methods, such as constructors and operators)
E	Event
!	Error string The rest of the string provides information about this error. C # The Compiler generates error messages for links that cannot be parsed.

 

The following is an example of C # code:

// Compile with:/DOC: docfilename. xml

 

/// <Summary>

/// Class level summary documentation goes here. </Summary>

/// <Remarks>

/// Longer comments can be associated with a type or member

/// Through the remarks tag </remarks>

Public class testclass

{

/// <Summary>

/// Store for the name property </Summary>

Private string _ name = NULL;

 

/// <Summary>

/// The class constructor. </Summary>

Public testclass ()

{

// Todo: Add constructor logic here

}

 

/// <Summary>

/// Name property </Summary>

/// <Value>

/// A value tag is used to describe the property value </value>

Public string name

{

Get

{

If (_ name = NULL)

{

Throw new system. Exception ("name is null ");

}

Return _ name;

}

}

 

/// <Summary>

/// Description for somemethod. </Summary>

/// <Param name = "S"> parameter description for S goes here </param>

/// <Seealso CREF = "system. String">

/// You can use the CREF attribute on any tag to reference a type or member

/// And the compiler will check that the reference exists. </seealso>

Public void somemethod (string S)

{

}

 

/// <Summary>

/// Some other method. </Summary>

/// <Returns>

/// Return results are described through the returns tag. </returns>

/// <Seealso CREF = "somemethod (string)">

/// Notice the use of the cref attribute to reference a specific method </seealso>

Public int someothermethod ()

{

Return 0;

}

 

/// <Summary>

/// The entry point for the application.

/// </Summary>

/// <Param name = "ARGs"> A list of command line arguments </param>

Static int main (system. String [] ARGs)

{

// Todo: Add code to start application here

Return 0;

}

}

XML Document Output:

<? XML version = "1.0"?>

-<Doc>

-<Assembly>

<Name> xmlcomment </Name>

</Assembly>

-<Members>

-<Member name = "T: testclass">

<Summary> class level summary documentation goes here. </Summary>

<Remarks> longer comments can be associated with a type or member through the remarks tag </remarks>

</Member>

-<Member name = "F: testclass. _ name">

<Summary> store for the name property </Summary>

</Member>

-<Member name = "M: testclass. # ctor">

<Summary> the class constructor. </Summary>

</Member>

-<Member name = "M: testclass. somemethod (system. String)">

<Summary> description for somemethod. </Summary>

<Param name = "S"> parameter description for S goes here </param>

<Seealso CREF = "T: system. string "> you can use the CREF attribute on any tag to reference a type or member and the compiler will check that the reference exists. </seealso>

</Member>

-<Member name = "M: testclass. someothermethod">

<Summary> some other method. </Summary>

<Returns> return results are described through the returns tag. </returns>

<Seealso CREF = "M: testclass. somemethod (system. String)"> notice the use of the cref attribute to reference a specific method </seealso>

</Member>

-<Member name = "M: testclass. Main (system. String [])">

<Summary> the entry point for the application. </Summary>

<Param name = "ARGs"> A list of command line arguments </param>

</Member>

-<Member name = "P: testclass. Name">

<Summary> Name property </Summary>

<Value> A value tag is used to describe the property value </value>

</Member>

</Members>

</DOC>