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

Question

我知道备注标签用于提供有关 class 的附加信息，但在悬停/调用 class 时它不会显示在智能感知中。我想知道它到底有什么用？

Answer 1

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

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

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

右键单击项目名称 -> 属性
转到构建选项卡
启用（选中），XML 文档文件选项

Answer 2

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

这是一篇相当古老的博客 post 讨论该主题，但您会明白要点的：

"Most developers I think are aware of the concept of using XML code comments to decorate .NET objects. There are really two benefits: 1) it shows this information in intellisense when you’re consuming the object and 2) you can production component documentation like MSDN."

来源：XML Code Comments and Sandcastle, demystified!

Answer 3

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

Visual Studio 的 IntelliSense 使用这些标签来提示您创建的 classes、函数和属性（如果它们已创建）正确如下：

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

这将创建 "XML comments" 并为您添加最常用的标签（例如，您方法的每个参数的参数标签）。
如果光标在 class 名称上方一行， 它将创建一个 <summary> 标签，如果它在 方法名称， 它将为每个参数额外创建 <param> 标签，并为 return 值创建一个 <returns> 标签。

你得到的直接好处是你输入的描述无处不在（不仅在声明中），你只需要在源代码中指向方法名或参数，如下所示：

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

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

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

示例：

/// <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 4

正如在 C# guide 中所读：

The <remarks> tag is used to add information about a type or a type member, supplementing the information specified with <summary>. This information is displayed in the Object Browser window.

因此 <summary> 用于元素的紧凑描述，而 <remarks> 用于完整描述。编写代码时，IntelliSense 会显示摘要，但在文档或更详细的视图中，会显示备注内容。使用 IntelliSense 显示完整描述将花费大量 space 和阅读时间。

Answer 5

就像@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 创建了

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

What is the purpose of remarks tag in c#

c#

.net

xmldocument

xml-comments