C # annotation syntax

Annotation syntax

To use the XML annotation function provided by C #, your annotation should start with a special annotation syntax. After ///, you can use pre-defined labels to annotate your code or insert your own defined labels. The custom tag will be added to the generated annotation document later.

Predefined tagsUsage <C> mark the text in the description as code <Code> provides a method to indicate multiple lines as code. <Example> example of specifying the usage method or other library members <Exception> allow you to specify possible exception classes <Include> allow you to reference comments in another file describing types and members in the source code, and use XML XPath syntax to describe the types and members in your source code. <List> insert a list to the XML comment document <Para> insert a paragraph to the XML annotation document <Param> describes a parameter. <Paramref> provides a method to indicate a word as a parameter. <Permission> allow you to add member access permissions to the document <Remarks> used to add information about a type <Returns> description Return Value <See> specified Link <Seealso> specify the text you want to see in the "see" section. <Summary> General description of type or type members <Value> description attribute

Example

The following example adds comments to common helloworld console applications:

Using system; Namespace helloworld { /// <Summary> /// Sample Hello world in C # /// </Summary> Public class helloworld { /// <Summary> /// Console application entry point /// <Param name = "ARGs"> command line arguments </param> /// <Returns> Status Code of 0 on successful run </returns> /// </Summary> Public static int main (string [] ARGs) { System. Console. writeline ("helloworld "); String name = system. Console. Readline (); Return (0 ); } } }

To generate an XML annotation document, we use the/DOC option when calling CSC to compile the source code:

CSC/DOC: helloworld. xml helloworld. CS

The generated results are as follows:

<? XML version = "1.0"?> <Doc> <Assembly> <Name> xmlcomment </Name> </Assembly> <Members> <Member name = "T: helloworld. helloworld"> <Summary> Sample Hello world in C # </Summary> </Member> <Member name = "M: helloworld. helloworld. Main (system. String [])"> <Summary> Console Application entry point <Param name = "ARGs"> command line arguments </param> <Returns> Status Code of 0 on successful run </returns> </Summary> </Member> </Members> </DOC>

 

HtmlPage www.elivn.com

You may ask yourself: How can I get HTML pages in good format? You can write your own XSL to convert the generated XML annotation document, or use Visual Studio. NET development tools. By using [generate annotation webpage] in the [tools] menu of vs. net, you can get a series of HTML pages that detail your project or solution. The following is an HTML page snapshot of the helloworld program generated by vs. Net:

Annotation syntax

To use the XML annotation function provided by C #, your annotation should start with a special annotation syntax. After ///, you can use pre-defined labels to annotate your code or insert your own defined labels. The custom tag will be added to the generated annotation document later.

Predefined tagsUsage <C> mark the text in the description as code <Code> provides a method to indicate multiple lines as code. <Example> example of specifying the usage method or other library members <Exception> allow you to specify possible exception classes <Include> allow you to reference comments in another file describing types and members in the source code, and use XML XPath syntax to describe the types and members in your source code. <List> insert a list to the XML comment document <Para> insert a paragraph to the XML annotation document <Param> describes a parameter. <Paramref> provides a method to indicate a word as a parameter. <Permission> allow you to add member access permissions to the document <Remarks> used to add information about a type <Returns> description Return Value <See> specified Link <Seealso> specify the text you want to see in the "see" section. <Summary> General description of type or type members <Value> description attribute

Example

The following example adds comments to common helloworld console applications:

Using system; Namespace helloworld { /// <Summary> /// Sample Hello world in C # /// </Summary> Public class helloworld { /// <Summary> /// Console application entry point /// <Param name = "ARGs"> command line arguments </param> /// <Returns> Status Code of 0 on successful run </returns> /// </Summary> Public static int main (string [] ARGs) { System. Console. writeline ("helloworld "); String name = system. Console. Readline (); Return (0 ); } } }

To generate an XML annotation document, we use the/DOC option when calling CSC to compile the source code:

CSC/DOC: helloworld. xml helloworld. CS

The generated results are as follows:

<? XML version = "1.0"?> <Doc> <Assembly> <Name> xmlcomment </Name> </Assembly> <Members> <Member name = "T: helloworld. helloworld"> <Summary> Sample Hello world in C # </Summary> </Member> <Member name = "M: helloworld. helloworld. Main (system. String [])"> <Summary> Console Application entry point <Param name = "ARGs"> command line arguments </param> <Returns> Status Code of 0 on successful run </returns> </Summary> </Member> </Members> </DOC>

 

HtmlPage www.elivn.com

You may ask yourself: How can I get HTML pages in good format? You can write your own XSL to convert the generated XML annotation document, or use Visual Studio. NET development tools. By using [generate annotation webpage] in the [tools] menu of vs. net, you can get a series of HTML pages that detail your project or solution. The following is an HTML page snapshot of the helloworld program generated by vs. Net: