c#中备注标记的用途是什么

Question

我知道remarks标签用于提供有关该类的其他信息,但在悬停/调用该类时它不会显示在intellisense中.我想知道它到底有用吗？

Answer 1

备注用于构建文档文件.它们用于更详细的注释,向"摘要"标记添加补充信息("摘要"标记在智能感知中显示).

生成的文档文件将采用XML格式.

要生成文档文件,您需要添加"/ doc"编译器选项.在visual studio中,您可以通过以下方式启用XML文档文件的生成:

1. 右键单击项目名称 - >属性
2. 转到"构建"选项卡
3. 启用(检查)XML文档文件选项

Answer 2

该<remarks> ... </remarks>标签是 XML 注释的可选部分，用于提供附加信息，例如，如果存在您希望其他开发人员注意的任何已知问题。在较新版本的 Visual Studio 中，此标记的内容也会显示在 IntelliSense 中。

Visual Studio 的IntelliSense使用这些标记来提供有关您创建的类、函数和属性的提示（如果它们已正确创建），如下所示：

在C#（以及 Visual Studio 的代码编辑器）中，可以通过键入 ///（三个正斜杠而不是两个）并按 Return 键轻松完成此操作，如下所示：

这将创建“XML 注释”并为您添加最常见的标签（例如方法的每个参数的参数标签）。
如果光标位于类名上方一行，它将创建一个<summary>标签，如果光标位于方法名称上方，它将<param>为每个参数创建额外的标签，并<returns>为返回值创建一个标签。

您直接获得的好处是，您输入的描述会显示在各处（不仅在声明中），您只需指向源代码中的方法名称或参数，如下所示：

如果您正在开发 Web API 函数并使用Swagger ，那么您将获得额外的好处，那么您可以在 Swagger 启动代码中引用 XML 注释。当您编译并运行它时，以及当显示 API 页面时，摘要和参数将立即在 Swagger 中显示 - 因此您可以将它们作为 API 文档的一部分。

其他标签，例如<remarks>当光标位于///注释内时由 IntelliSense 建议的标签（请参见下面的示例）。据我所知，IntelliSense 仅使用<summary>和标签。<param>如果这些标签中的任何一个包含cref属性，您可以引用其他项目（如示例中所示）。较新版本的 Visual Studio 可以显示附加标签（请参阅此答案下面riQQ 的 评论）。

此外，正如其他答案所解释的那样，您可以创建一个XML 文档，可以使用第 3 方工具（例如Sandcastle Help file builder）将其转换为超链接文档或静态 html 文件。

例子：

/// <summary>
/// Description what the class does
/// </summary>
/// <remarks>
/// This is an example class showing how it works.
/// </remarks>
public class MyClass
{
    /// <summary>
    /// Description what the function does
    /// </summary>
    /// <param name="param1">Description what the parameter does 
    ///   Optional tags inside param1:
    ///    <c></c> <code></code> <list type=""></list> <paramref name="param1"/>
    ///    <para></para>
    /// </param>
    /// <param name="param2">Description what the parameter does</param>
    /// <returns>Description about the return value</returns>
    public string MyMethod(int param1, string param2)
    {
        return "Some value: " + MyProperty;
    }

    /// <summary>
    /// Description what the property does
    /// </summary>
    /// <see cref="MyMethod(int, string)"/>
    string MyProperty { get; set; }

    // optional tags (valid for class and methods):

    /// <completionlist cref=""/>
    /// <example></example>
    /// <exception cref=""></exception>
    /// <include file='' path='[@name=""]'/>
    /// <permission cref=""></permission>
    /// <remarks></remarks>
    /// <see cref=""/>
    /// <seealso cref=""/>
}