c#中备注标签的作用是什么

Question

我了解备注标签用于提供有关课程的其他信息，但在悬停/调用该课程时不会以智能感知显示。我想知道它到底在哪里有用？

Answer 1

备注用于构建文档文件。它们用于更详细的 cmets，向“summary”标签添加补充信息（“summary”标签确实显示在智能感知中）。

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

要生成文档文件，您需要添加“/doc”编译器选项。 在 Visual Studio 中，您可以通过以下方式启用 XML 文档文件的生成：

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

Answer 2

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

Visual Studio 的 IntelliSense 使用这些标记来提供有关您创建的类、函数和属性的提示，前提是它们按如下方式正确创建：

在 C#（以及 Visual Studio 的代码编辑器）中，这很容易通过键入 ///（三个正斜杠而不是两个）并按 Return 来完成，如下所示：

这将创建"XML comments" 并为您添加最常见的标签（例如，您方法的每个参数的参数标签）。
如果光标在类名的上方，会创建<summary>标签，如果在方法名的上方，会额外创建@每个参数使用 987654333@ 标签，返回值使用 <returns> 标签。

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

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

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

此外，正如其他答案所解释的，您可以创建一个 XML 文档，可以使用第三方工具（例如 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=""/>
}

Answer 3

.NET 中的许多标签在生成文档时都会被真正利用。也许，最受欢迎和我使用的是 Sandcastle。

这是一篇相当老的博文，讨论这个话题，但你会明白的：

“我认为大多数开发人员都知道使用 XML 代码 cmets 来装饰 .NET 对象的概念。实际上有两个好处：1）当您使用对象时，它会以智能感知方式显示此信息，以及 2）您可以生产组件文档，如 MSDN。”

来源：XML Code Comments and Sandcastle, demystified!

Answer 4

就像@Dodger 写的那样。 为了给你一个视觉印象，这里有一个示例

代码：

/// <summary>A <see cref="MonitorGroup"/> device.</summary>
/// <remarks>If not created with belonging new <see cref="Decoder"/> the properties for <see cref="MonitorGroup.Decoder"/>
/// and <see cref="MonitorGroup.MonitorNumber"/> are <c>null</c>.
/// <para>Refactoring necessary 
/// <list type="bullet">
/// <item><description>a MonitorGroup can connect to several decoders</description></item>
/// <item><description>a MonitorGroup can be connected to several monitors.</description></item>
/// </list>
/// a MonitorGroup can connect to several decoders.</para>
/// </remarks>
/// <seealso cref="MonitorGroup" />
public class MonitorGroup : Device<MonitorGroup>

现在在 Visual Studio 中显示为

DocFX 创造了这个

Answer 5

可以在C# guide阅读：

<remarks> 标签用于添加关于类型或类型成员的信息，补充<summary> 指定的信息。此信息显示在对象浏览器窗口中。

所以<summary> 用于元素的简洁描述，<remarks> 用于完整描述。编写代码时，IntelliSense 会显示摘要，但在文档或更详细的视图中，会显示备注内容。使用 IntelliSense 显示完整说明会占用大量空间和时间来阅读。