更新记录
转载请注明出处：
2022年9月22日 发布。
2022年9月10日 从笔记迁移到博客。
标准XML标签（Standard XML Documentation Tags）
<summary> //简要说明
<param> //参数说明
<returns> //返回值说明
<example> //实例说明
<code> //代码说明
<seealso> //see also 选项说明
<value> //描述属性
<summary>...</summary>
Indicates the tool tip that IntelliSense should display for the type or member.
Typically, a single phrase or sentence.
<remarks>...</remarks>
Additional text that describes the type or member.
Documentation generators pick this up and merge it into the bulk of a type or member’s description.
<param name="name">...</param>
Explains a parameter on a method.
<returns>...</returns>
Explains the return value for a method.
<exception [cref="type"]>...</exception>
Lists an exception that a method might throw (cref refers to the exception type).
cref指示异常的类型
<permission [cref="type"]>...</permission>
Indicates an IPermission type required by the documented type or member.
<example>...</example>
Denotes an example (used by documentation generators).
This usually contains both description text and source code
(source code is typically within a tag).
<c>...</c>
Indicates an inline code snippet. This tag is usually used within an block.
<code>...</code>
Indicates a multiline code sample. This tag is usually used within an block.
一般放置在
<see cref="member">...</see>
Inserts an inline cross-reference to another type or member.
HTML documentation generators typically convert this to a hyperlink.
The compiler emits a warning if the type or member name is invalid.
<seealso cref="member">...</seealso>
Cross-references another type or member.
Documentation generators typically write this
into a separate “See Also” section at the bottom of the page.
<paramref name="name"/>
References a parameter from within a
or tag.
<list>...</list>
<list type=[ bullet | number | table ]>
<listheader>
<term>...</term>
<description>...</description>
</listheader>
<item>
<term>...</term>
<description>...</description>
</item>
</list>
Instructs documentation generators to emit a bulleted, numbered, or table-style list.
<para>...</para>
Instructs documentation generators to format the contents into a separate paragraph.
<include>...</include>
<include file='filename' path='tagpath[@name="id"]'>
...
</include>
Merges an external XML file that contains documentation. The path attribute denotes an XPath query to a specific element in that file.
注释实例
/// <summary>
/// DataStorage is used to persist and retrieve
/// employee data from the files
/// </summary>
class DataStorage
{
/// <summary>
/// Save an employee object to a file
/// named with the employee name
/// </summary>
/// <remarks>
/// This method uses
/// <seealso cref="System.IO.FileStream"/>
/// in addition to
/// <seealso cref="System.IO.StreamWriter"/>
/// </remarks>
/// <param name="employee">
/// The employee to persist to a file</param>
/// <data>January 1, 2000</date>
public static void Store(Employee employee)
{
// ...
}
/** <summary>
* Loads up an employee object
* </summary>
* <remarks>
* This method uses
* <seealso cref="System.IO.FileStream"/>
* in addition to
* <seealso cref="System.IO.StreamReader"/>
* </remarks>
* <param name="firstName">
* The first name of the employeee</param>
* <param name="lastName">
* The last name of the employee</param>
* <returns>
* The employee object corresponding to the names
* </returns>
* <date>January 1, 2000</date>**/
public static Employee Load(string firstName, string lastName)
{
// ...
}
}
配置项目的XML注释文档导出
在.csproj 项目配置文件中，添加以下代码
<PropertyGroup>
<DocumentationFile>SomeFile.xml</DocumentationFile>
</PropertyGroup>
作用：
智能提示（IntelliSense），比如Visual Studio中
使用第三方工具生成代码的文档
第三方XML生成API文档工具
NDoc http://ndoc.sourceforge.net/
Sandcastle https://github.com/EWSoftware/SHFB
XmlCommentMarkDownGenerator https://github.com/Pxtl/XmlCommentMarkDownGenerator
GhostDoc http://submain.com/
编译器输出XML文档：https://docs.microsoft.com/zh-cn/dotnet/csharp/language-reference/compiler-options/doc-compiler-option
标签：XML,...,Tags,C#,member,generators,employee,type
From： https://www.cnblogs.com/cqpanda/p/16712675.html