C # XML document comment file format,

C # XML document comment file format,

When writing C # code, you only need to add XML document annotations in the annotations according to the format. For example:

/// <Summary> /// class annotation. /// </Summary> public class MyClass {}

You can set "properties-> Generate-> output-> XML document file" of the project to generate an XML file containing all document comments for the current project. It can be used for smart prompts of Visual Studio or to generate documents using tools such as Sandcastle.

Next, we will introduce the format and rules of the generated XML file, which are based on the results generated by the C # compiler.

I. XML document comment File Format

The file format for XML document comments is very simple. It is a list containing all comments. A simple example is as follows:

The root node of the XML file isdoc, Which contains two subnodesassemblyAndmembers. WhereassemblyIs the Assembly name corresponding to the XML file,membersContains multiplememberNodes. All comments are listed (public, protected, or private ).memberNodenameAn element is a unique identifier that corresponds to the classes, methods, attributes, fields, and other Members defined in the dataset. ThecrefAll attributes are converted to identifiers instead of the specified Member names.

<? Xml version = "1.0"?> <Doc> <assembly> <name> Cyjb </name> </assembly> <members> <member name = "T: Cyjb. arrayExt "> <summary> provides an Array Extension Method. </Summary> </member> <member name = "M: Cyjb. arrayExt. left ''1 (''0 [], System. int32) "> <summary> truncates a part from the left side of the current array. </Summary> <typeparam name = "T"> type of elements in the array. </Typeparam> <param name = "array"> return the left part of the array. </Param> <param name = "length"> Number of elements to be intercepted. If it is <c> 0 </c>, an empty array is returned. If the length is greater than or equal to the length of <paramref name = "array"/>, a shortest copy of the entire array is returned. </Param> <returns> the part truncated from the left end of the specified array. </Returns> <exception cref = "T: System. ArgumentNullException"> <paramref name = "array"/> is <c> null </c>. </Exception> <exception cref = "T: System. ArgumentOutOfRangeException"> <paramref name = "length"/> less than <c> 0 </c>. </Exception> </member>... </members> </doc>

Ii. Unique identifier rules

Unique Identifier alwaysType:FullNameFormat, whereTypeIndicates the type of the corresponding member,FullNameIs the fully qualified name of the corresponding member.:Separated.

Member typeTypePossible values include:

• N-Namespace.
• T-Type, including class, interface, struct, enumeration, and delegate.
• F-Field.
• P-Attribute.
• M-Methods, including common methods, constructors, and operator overloading.
• E-Events.
• !-The error member is generally because the compiler cannot identify the specified member type, for example<see cref="MemberNotExists"/>Will be converted<see cref="!:MemberNotExists"/>.

Fully Qualified nameFullNameSimilar to the fully qualified names of members, they all start from the root of the namespace and are separated by vertices. The difference is:

A complete instance is shown below, which lists the unique identifiers of each member:

using System.Collections.Generic;// Identifier is N:Cyjbnamespace Cyjb{    /// <summary>    /// Identifier is T:Cyjb.SampleType    /// </summary>    public unsafe class SampleType    {        /// <summary>        /// Identifier is F:Cyjb.SampleType.SampleValue        /// </summary>        public const int SampleValue = 0;        /// <summary>        /// Identifier is F:Cyjb.SampleType.SampleValue2        /// </summary>        public int SampleValue2 = 0;        /// <summary>        /// Identifier is M:Cyjb.SampleType.#ctor        /// </summary>        public SampleType() { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.#ctor(System.Int32)        /// </summary>        public SampleType(int value) { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.SampleMethod        /// </summary>        public void SampleMethod() { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.SampleMethod(System.Int32,System.Int32@,System.Int32*)        /// </summary>        public void SampleMethod(int a, ref int b, int* c) { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.SampleMethod(System.Int32[],System.Int32[0:,0:],System.Int32[][])        /// </summary>        public void SampleMethod(int[] a, int[,] b, int[][] c) { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.SampleMethod``1(``0,``0[],System.Collections.Generic.IList{``0},System.Collections.Generic.IList{System.Collections.Generic.IList{``0[]}})        /// </summary>        public void SampleMethod<T>(T a, T[] b, IList<T> c, IList<IList<T[]>> d) { }        /// <summary>        /// Identifier is M:Cyjb.SampleType.op_Addition(Cyjb.SampleType,Cyjb.SampleType)        /// </summary>        public static SampleType operator +(SampleType x, SampleType y) { return null; }        /// <summary>        /// Identifier is M:Cyjb.SampleType.op_Explicit(System.Int32)~Cyjb.SampleType        /// </summary>        public static explicit operator SampleType(int x) { return null; }        /// <summary>        /// Identifier is M:Cyjb.SampleType.op_Implicit(Cyjb.SampleType)~System.Int32        /// </summary>        public static implicit operator int(SampleType x) { return 0; }        /// <summary>        /// Identifier is P:Cyjb.SampleType.SampleProperty        /// </summary>        public int SampleProperty { get; set; }        /// <summary>        /// Identifier is P:Cyjb.SampleType.Item(System.Int32)        /// </summary>        public int this[int index] { get { return 0; } }        /// <summary>        /// Identifier is T:Cyjb.SampleType.SampleDelegate        /// </summary>        public delegate void SampleDelegate(int a);        /// <summary>        /// Identifier is E:Cyjb.SampleType.SampleEvent        /// </summary>        public event SampleDelegate SampleEvent;        /// <summary>        /// Identifier is T:Cyjb.SampleType.NestedType        /// </summary>        public class NestedType { }        /// <summary>        /// Identifier is T:Cyjb.SampleType.NestedType2`1        /// </summary>        public class NestedType2<T>        {            /// <summary>            /// Identifier is M:Cyjb.SampleType.NestedType2`1.TestMethod``1(`0,``0,System.Collections.Generic.IDictionary{`0,``0})            /// </summary>            public void TestMethod<T2>(T a, T2 b, IDictionary<T, T2> c) { }        }    }}