【语言-c#】C# 注释详细介绍说明

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Threading.Tasks;

namespace XDC
{
    /// Comment for class
    public class EClass : System.Exception
    {
        // class definition...
    }
    class XML_Documentation_Comments
    {
        /// <summary>
        /// <c>Tag_c</c> is a method in the <c>XML_Documentation_Comments</c> class.
        /// </summary>
        public static void Tag_c(int Int1)
        {
            //语法 XML        <c>text</c>
            //参数 text       要指示为代码的文本。
            //备注            使用 <c> 标记可以指示应将说明内的文本标记为代码。 使用 <code> 指示作为代码的多行文本。
            //                使用 /doc 进行编译可以将文档注释处理到文件中。
        }

        /// <summary>
        /// The Tag_code method.
        /// </summary>
        /// <example> 
        /// This sample shows how to call the <see cref="Tag_code"/> method.
        /// <code>
        /// class XML_Documentation_Comments 
        /// {
        ///     static int Main() 
        ///     {
        ///        return Tag_code();
        ///     }
        /// }
        /// </code>
        /// </example>
        public static int Tag_code()
        {
            //语法 XML        <code>content</code> 
            //参数 content    要标记为代码的文本。
            //备注            <code> 标记可将多行内容指示为代码。 使用 <c> 指示应将说明内的文本标记为代码。
            //                使用 /doc 进行编译可以将文档注释处理到文件中。
            return 0;
        }
        /// <summary>
        /// The Tag_example method.
        /// </summary>
        /// <example> 
        /// This sample shows how to call the <see cref="Tag_example"/> method.
        /// <code>
        /// class XML_Documentation_Comments 
        /// {
        ///     static int Main() 
        ///     {
        ///        return Tag_example();
        ///     }
        /// }
        /// </code>
        /// </example>
        public static int Tag_example()
        {
            //语法 XML          <example>description</example>
            //参数 description  代码示例的说明。
            //备注              借助 <example> 标记，可以指定如何使用方法或其他库成员的示例。 这通常涉及到使用 <code> 标记。
            //                  使用 /doc 进行编译可以将文档注释处理到文件中。
            return 0;
        }
        /// <exception cref="System.Exception">Thrown when...</exception>
        public void Tag_exception()
        {
            try
            {
                //语法 XML          <exception cref="member">description</exception>  
                //参数 cref="member" 对当前编译环境中出现的一个异常的引用。 编译器检查是否存在给定的异常，并将 member 转换为输出 XML 中的规范的元素名称。
                //                   member 必须出现在双引号 (" ") 内。
                //                  有关如何设置 member 格式以引用泛型类型的详细信息，请参阅处理 XML 文件。
                //     description  异常的说明。
                //备注              <exception> 标记让你指定可引发的异常。 此标记可应用于方法、属性、事件和索引器的定义。
                //                  使用 /doc 进行编译可以将文档注释处理到文件中。
                //                  有关异常处理的详细信息，请参阅异常和异常处理。
            }
            catch (EClass)
            {
            }
        }
        /// <summary>
        /// Here is an example of a bulleted list:
        /// <list type="bullet">
        /// <item>
        /// <description>Item 1.</description>
        /// </item>
        /// <item>
        /// <description>Item 2.</description>
        /// </item>
        /// </list>
        /// </summary>
        public void Tag_list()
        {
            //语法 XML
            //  <list type="bullet" | "number" | "table">  
            //      < listheader >
            //          < term > term </ term >
            //          < description > description </ description >
            //      </ listheader >
            //      < item >
            //          < term > term </ term >
            //          < description > description </ description >
            //      </ item >
            //  </ list >

            //参数 
            //  term            要定义的术语，将在 description 中进行定义。
            //  description     项目符号或编号列表中的项或 term 的定义。

            //备注
            //  <listheader> 块用于定义表或定义列表的标题行。 定义表时，只需提供标题中的术语的项。
            //  列表中的每个项均使用 <item> 块指定。 创建定义列表时，需要同时指定 term 和 description。 但是，对于表、项目符号列表或编
            //  号列表，只需提供 description 的项。
            //  列表或表可根据需要具有多个 <item> 块。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
        }
        /// <summary>
        /// <para>para 1</para>
        /// <para>para 2</para>
        /// </summary>
        public void Tag_para()
        {
            //语法 XML
            //  <para>content</para>  

            //参数 
            //  content     段落文本。

            //备注
            //  <para> 标记用于标记内，例如 <summary>、<remarks> 或 <returns>，允许向文本添加结构。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
        }
        /// <summary>
        /// Multiple parameters.
        /// </summary>
        /// <param name="Int1">Used to indicate status.</param>
        /// <param name="Float1">Used to specify context.</param>
        public void Tag_param(int Int1, float Float1)
        {
            //语法 XML
            //  <param name="name">description</param>  

            //参数 
            //  name            方法参数的名称。 用双引号 (" ") 将名称引起来。
            //  description     参数的说明。

            //备注
            //  在方法声明的注释中，应使用 <param> 标记来描述方法参数之一。 若要记录多个参数，请使用多个 <param > 标记。
            //  <param> 标记的文本将显示在 IntelliSense、对象浏览器和代码注释 Web 报表中。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
        }
        /// <summary>
        /// Tag_paramref is a method in the XML_Documentation_Comments class.  
        /// The <paramref name="Int1"/> parameter takes a number.
        /// </summary>
        /// <param name="Int1"></param>
        public void Tag_paramref(int Int1)
        {
            //语法 XML
            //  <paramref name="name"/>

            //参数 
            //  name            要引用的参数的名称。 用双引号 (" ") 将名称引起来。

            //备注
            //  <paramref> 标记提供一种方式，用于指示 <summary> 或 <remarks> 块等代码注释中的单词引用某个参数。 可以处理 XML 文件以明
            //  显的方式设置此单词的格式，如使用粗体或斜体。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
        }

        /// <permission cref="System.Security.PermissionSet">Everyone can access this method.</permission>
        public void Tag_permission()
        {
            //语法 XML
            //  <permission cref="member">description</permission>  

            //参数 
            //  cref="member"   对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的代码元素，并将 member 转换为输出 
            //                  XML 中规范的元素名称。 成员必须出现在双引号 (" ") 内。
            //                  有关如何创建对泛型类型的 cref 引用的信息，请参阅 <see>。
            //  description     对成员访问权限的说明。

            //备注
            //  使用 <permission> 可以记录成员访问权限 PermissionSet 类可指定对成员的访问权限。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
        }
        /// <returns>Returns zero.</returns>
        public int Tag_returns()
        {
            //语法 XML
            //  <returns>description</returns>  

            //参数 
            //  description     返回值的说明。

            //备注
            //  在方法声明的注释中应使用 <returns> 标记来描述返回值。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            return 0;
        }
        /// <summary>Tag_see is a method in the XML_Documentation_Comments class.
        /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
        /// <seealso cref="XML_Documentation_Comments.Tag_see"/>
        /// </summary>
        public int Tag_see()
        {
            //语法 XML
            //  <see cref="member"/> 

            //参数 
            //  cref="member"     对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的码位元素，并将 member 传递到输出 XML 中的元素名称。
            //                    将成员置于双引号 (" ") 内。

            //备注
            //  通过 <see> 标记可以从文本内指定链接。 使用 <seealso> 指示文本应该放在“另请参阅”部分中。 使用 cref 属性创建指向代码元素的文
            //  档页的内部超链接。
            //  使用 /doc 进行编译以便将文档注释处理到文件中。
            return 0;
        }
        /// <summary>Tag_seealso is a method in the XML_Documentation_Comments class.
        /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
        /// <seealso cref="XML_Documentation_Comments.Tag_see"/>
        /// </summary>
        public int Tag_seealso()
        {
            //语法 XML
            //  <seealso cref="member"/>  

            //参数 
            //  cref="member"     对可从当前编译环境调用的成员或字段的引用。 编译器检查是否存在给定的码位元素，并将 member 传递到输出 XML 中的元素名称。
            //                    member 必须在双引号 (" ") 内。
            // 有关如何创建对泛型类型的 cref 引用的信息，请参阅 <see>。

            //备注
            //  使用 <seealso> 标记，可以指定想要在“另请参阅”部分中显示的文本。 使用 <see> 从文本内指定链接。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            return 0;
        }
        /// <summary>Tag_summary is a method in the XML_Documentation_Comments class.
        /// <para>Here's how you could make a second paragraph in a description. <see cref="System.Console.WriteLine(System.String)"/> for information about output statements.</para>
        /// <seealso cref="XML_Documentation_Comments.Tag_see"/>
        /// </summary>
        public int Tag_summary()
        {
            //语法 XML
            //  <summary>description</summary>  

            //参数 
            //  description     对象的摘要。

            //备注
            //  <summary> 标记应当用于描述类型或类型成员。 使用 <remarks> 可针对某个类型说明添加补充信息。 使用 cref 属性可启用文档工
            //  具（如 DocFX 和 Sandcastle）来创建指向代码元素的文档页的内部超链接。
            //  <summary> 标记的文本是唯一有关 IntelliSense 中的类型的信息源，它也显示在对象浏览器窗口中。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。 若要基于编译器生成的文件创建最终文档，可以创建一个自定义工具，也可以使用 
            //  DocFX 或 Sandcastle 等工具。
            return 0;
        }
        /// <summary>
        /// Creates a new array of arbitrary type <typeparamref name="T"/>
        /// </summary>
        /// <typeparam name="T">The element type of the array</typeparam>
        public static T[] Tag_typeparam<T>(int n)
        {
            //语法 XML
            //  <typeparam name="name">description</typeparam>  

            //参数 
            //  name            类型参数的名称。 用双引号 (" ") 将名称引起来。
            //  description     类型参数的说明。

            //备注
            //  在泛型类型或方法声明的注释中，应使用 <typeparam> 标记来描述类型参数。 为泛型类型或方法的每个类型参数添加标记。
            //  有关详细信息，请参阅泛型。
            //  <typeparam> 标记的文本将显示在 IntelliSense、对象浏览器窗口代码注释 Web 报表。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            return new T[n];
        }
        /// <summary>
        /// Creates a new array of arbitrary type <typeparamref name="T"/>
        /// </summary>
        /// <typeparam name="T">The element type of the array</typeparam>
        public static T[] Tag_typeparamref<T>(int n)
        {
            //语法 XML
            //  <typeparamref name="name"/>  

            //参数 
            //  name            类型参数的名称。 用双引号 (" ") 将名称引起来。

            //备注
            //  有关泛型类型中的类型参数及方法的详细信息，请参阅泛型。
            //  通过此标记，文档文件的使用者可显著设置字体格式，例如采用斜体。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            return new T[n];
        }
        private string _name;
        /// <summary>The Name property represents the employee's name.</summary>
        /// <value>The Name property gets/sets the value of the string field, _name.</value>
        public string Tag_value
        {
            //语法 XML
            //  <value>property-description</value>  

            //参数 
            //  property-description            属性的说明。

            //备注
            //  <value> 标记可以描述属性表示的值。 请注意，在 Visual Studio .NET 开发环境中通过代码向导添加属性时，将添加新属性的 
            //  <summary> 标记。 然后，应手动添加 <value> 标记，描述属性表示的值。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            get
            {
                return _name;
            }
            set
            {
                _name = value;
            }
        }
        public class Tag_cref_Attribute
        {
            //XML 文档标记中的 cref 属性是指“代码引用”。 它指定标记的内部文本是一个代码元素，例如类型、方法或属性。 文档工具（例如 DocFX 和 Sandcastle）使用 cref 属性自动生成指向记录类型或成员的页面的超链接。
            /// <summary>
            /// This sample shows how to specify the <see cref="Tag_cref_Attribute"/> constructor as a cref attribute.
            /// </summary>
            public Tag_cref_Attribute()
            { }
            /// <summary>
            /// This sample shows how to specify the <see cref="Tag_cref_Attribute(int)"/> constructor as a cref attribute.
            /// </summary>
            public Tag_cref_Attribute(int value)
            { }

            /// <summary>
            /// The GetZero method.
            /// </summary>
            /// <example> 
            /// This sample shows how to call the <see cref="GetZero"/> method.
            /// <code>
            /// class TestClass 
            /// {
            ///     static int Main() 
            ///     {
            ///         return GetZero();
            ///     }
            /// }
            /// </code>
            /// </example>
            public static int GetZero()
            {
                return 0;
            }

            /// <summary>
            /// The GetGenericValue method.
            /// </summary>
            /// <remarks> 
            /// This sample shows how to specify the <see cref="GetGenericValue"/> method as a cref attribute.
            /// </remarks>
            public static T GetGenericValue<T>(T para)
            {
                return para;
            }

            /// <summary>
            /// GenericClass.
            /// </summary>
            /// <remarks> 
            /// This example shows how to specify the <see cref="GenericClass{T}"/> type as a cref attribute.
            /// </remarks>
            class GenericClass<T>
            {
                // Fields and members.
            }

            class Program
            {
                static int Main()
                {
                    return Tag_cref_Attribute.GetZero();
                }
            }
        }
        /// <summary>
        /// You may have some primary information about this class.
        /// </summary>
        /// <remarks>
        /// You may have some additional information about this class.
        /// </remarks>
        public class Tag_remark
        {
            //语法 XML
            //  <remarks>description</remarks>  

            //参数 
            //  description     对成员的说明。

            //备注
            //  <remarks> 标记用于添加有关某个类型的信息，从而补充由 <summary> 指定的信息。 此信息显示在对象浏览器窗口中。
            //  使用 /doc 进行编译可以将文档注释处理到文件中。
            static void Main()
            {

            }
        }

        /// <include file='xml_include_tag.xml' path='MyDocs/MyMembers[@name="test"]/*' />
        public class Tag_include
        {
            /// <include file='xml_include_tag.xml' path='MyDocs/MyMembers[@name="test2"]/*' />
            static void Main()
            {
                //语法 
                //  XML         <include file='filename' path='tagpath[@name="id"]' />  

                //参数 
                //  filename    包含文档的 XML 文件的名称。 可使用相对于源代码文件的路径限定文件名。 使用单引号 (' ') 将 filename 括起来。
                //  tagpath     filename 中标记的路径，它指向标记 name。 使用单引号 (' ') 将路径括起来。
                //  name        标记中的名称说明符（位于注释之前）；name 将有 id。
                //  id          标记的 ID（位于注释之前）。 用双引号 (" ") 将 ID 括起来。

                //备注             
                //  通过 <include> 标记，可在其他文件中引用描述源代码中类型和成员的注释。 这是对直接在源代码文件中放入文档注释的替代方法。
                //  通过将文档放入不同文件，可以单独从源代码对文档应用源控件。 一人可以签出源代码文件，而其他人可以签出文档文件。
                //  <include> 标记使用 XML XPath 语法。 有关如何自定义 <include> 的用法，请参阅 XPath 文档。

                //xml_include_tag.xml  包含在项目中 
                //文件属性
                //  复制到输出目录      不复制
                //  生成操作            内容
                //
                //  <?xml version="1.0" encoding="utf-8"?>   
                //  < MyDocs >  
                //  < MyMembers name = "test" >
                //  < summary >
                //  The summary for this type.
                //  </ summary >
                //  </ MyMembers >
                //  < MyMembers name = "test2" >
                //  < summary >
                //  The summary for this other type.
                //  </ summary >
                //  </ MyMembers >
                //  </ MyDocs >
            }
        }
    }
}