XML comment in C #

XML comment in C #
The previous article mentioned how to use sandcastle to create a C # Help document. This requires you to insert an XML comment in the source file to appear in the form. C #'s "// <> </>" annotation is extracted during XML compilation. It is an essential source for sandcastle to automatically generate CHM help documents.

========================================================== ==============================
Directory
I. Common tags
<Summary>
<Remarks>
<Para>
<Param>
<Paramref>
<Returns>
<See>
<Seealso>
<Example>
<C>
<Code>
<Value>
Ii. sample source code
3. Other tags:
<Typeparam>
<Typeparamref>
<List>
<Item>
<Term> and <description>
<Exception>
<Include>
4. Insert images and other resources into comments
5. Other considerations
Vi. References
========================================================== ==============================

I. Common tags

Common annotations for XML documents include <summary> <remark> <param> <returns> <para>.

<Summary>It is used to describe the type or type member function and is marked before it is declared.

<Remarks>It is used to add supplementary information about a certain type, such as a class chart (how to insert the fourth point under the image resource and then describe it ). The <remarks> annotation can be embedded in <summary> or after <summary>. Embedded in <summary>, the description table of the class appears on the namespace page (figure 1). Parallel to <summary>, the description page of the class appears (figure 2 ).

<Para>Can be embedded in the comment, add the second Description: (here embedded in <summary>)

<Param>A tag is used to describe a parameter of a method in the annotation of a method declaration. The syntax is <Param name = "paramname"> description </param>.

<Paramref>It is used to reference a parameter in a word in a code comment, so that the document sets the format of the word in a unique way (usually italic. The syntax is <paramref name = "paramname"/>.

<Returns>Used to describe the return value of a method declaration annotation.

<See>Tags are used to specify links from the text. The syntax is <see CREF = "member"/>.

<Seealso>The label instruction text is placed in the "see" section. The syntax is <seealso CREF = "member"/>. Cref = "member" refers to the 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.

The preceding labels are used as examples:

<Example>The example that specifies the usage method or other library members, which often involves <code>.

<C>Mark the text in the description as code.

<Code>Multiple lines of text in the description are marked as code.

Example:

<Value>A tag is used to describe the value of a property.

Slave --------------------------------------------------------------------------------------------------------------------------------

Ii. sample source code

Appendix: source code used in the preceding example:
// Testclass. CS
Using system;
Using system. Collections. Generic;
Using system. text;

Namespace xmltag
{
/// <Summary>
/// This is a test class
/// </Summary>
/// <Remarks>
/// You may have some additional information about this class. <br/>
/// There's the class digoal. <br/>
///
/// </Remarks>
Public class testclass
{
/// <Summary> dowork is a method in the testclass class.
/// <Para> here's how you cocould make a second paragraph in a description. <br/>
/// The <paramref name = "aparam"/> parameter takes a number. <br/>
/// <See CREF = "testclass. avalue"/> for information about output statements.
/// </Para>
/// <Seealso CREF = "testclass. getzero"/>
/// </Summary>
/// <Param name = "aparam"> used to indicate status. </param>
/// <Returns> Returns none. </returns>
Public static void dowork (INT aparam)
{
// System. Console. writeline (system. String );
}

/// <Summary>
/// The getzero method.
/// </Summary>
/// <Returns> Returns zero. </returns>
/// <Example> This sample shows how to call the getzero method.
/// <Code>
/// Class myclass
///{
/// Static int main ()
///{
/// Return getzero ();
///}
///}
/// </Code>
/// </Example>
Public static int getzero ()
{
Return 0;
}

Private string _ value;

/// <Value> the avalue property gets/sets the _ value data member.
/// </Value>
Public String avalue
{
Get
{
Return _ value;
}
Set
{
_ Value = value;
}
}
}
}
The overview:

Slave --------------------------------------------------------------------------------------------------------------------------------

3. Other tags

<Typeparam>Tags are used to mark type parameters in comments of generic type or method declaration. The syntax is <typeparam name = "typename"> description </typeparam>.

<Typeparamref>Make the document set the Word format in a unique way (usually italic. The syntax is <typeparamref name = "typename"/>.

<List>Create a list. The syntax is <list type = "Bullet" | "Number" | "table"> </List>.

<Item>Each item in the list uses a <item> block description.

<Term>And<Description>Generally, you must specify both the term and description when creating a definition list. In particular, for tables, project symbol tables, and number lists, you only need to provide an item for description.
Example:
/// <Summary> here is an example of a bulleted list:
/// <List type = "Bullet">
/// <Listheader>
/// <Term> the title </term>
/// <Description> something </description>
/// </Listheader>
/// <Item>
/// <Description> Item 1. </description>
/// </Item>
/// <Item>
/// <Description> Item 2. </description>
/// </Item>
/// </List>
/// </Summary>

<Exception>Label is used to indicate exceptions. The syntax is <exception CREF = "member"> description </exception>.

<Include>Tags are used to reference comments in another file that describes types and members in source code. The syntax is <include file = 'filename' Path = 'tagpath [@ name = "ID"] '/>. Filename is the file name of the document to be included. The file name can be limited by tagpath. Note that filename is in single quotation marks ''. Name is the name specifier in the mark of the front side of the comment. name has an ID, note that the ID is in double quotation marks.

Slave --------------------------------------------------------------------------------------------------------------------------------

4. Insert images and other resources into comments

In the description of sandcastlegui, you can know that you can insert images and other resources in the generated documents, but you cannot perform online search. So I sent a help email to the author of sandcastlegui, with the idea of trying it out. I was touched by the fact that I replied to the email two hours later and attached the operation process in detail. I would like to thank the author again.
Procedure:
Step 1: Create required image resources and place them in a separate folder. Note that subfolders are not included.
Step 2: Declare a reference to the resource in the source code. Note that the file name must be referenced and cannot contain a path.
For example:
/// <Summary>
/// This class does something.
/// </Summary>
/// <Remarks>
/// There is a class digoal. <br/>
///
/// </Remarks>
Step 3: When setting sandcastlegui, select the folder for storing image resources in the "directory to include in documentation (optional)" option.
Step 4: After other parameters are set, execute sandcastlegui.
Example:

Slave --------------------------------------------------------------------------------------------------------------------------------

5. Other considerations

1. Folders that contain compiled XML and DLL source files cannot contain subfolders.
2. Note that when a CHM File is generated, the document that stores the file will be cleared first.
3. The generated CHM document cannot be placed in a path with the "#" character; otherwise, the "Page cannot be opened" error may occur.

Slave --------------------------------------------------------------------------------------------------------------------------------

Vi. References:

Msdn (C # programming guide): suggested document annotation mark
Http://msdn2.microsoft.com/zh-cn/library/5ast78ax (vs.80). aspx

Thanks to the author of sandcastlegui, inchlorophyll.
Http://www.inchl.nl