在Visual Studio 2010中C#中的XML标签"see"和"seealso"是什么意思？

Question

当您在Visual Studio 2010中工作并对方法编写注释并单击输入时,Visual Studio 2010允许您创建"查看"和"另请参阅"XML注释.

如果你输入评论"看"并按TAB然后它看起来像

/// <see cref=""/>
/// <seealso cref=""/> 

它在C#中的含义是什么？

Answer 1

<see />最初<seealso />是用于完全不同目的的完全不同的标签，但今天（也许是认识到当时的情况是多么令人困惑）几乎被相同地对待，至少在大多数人与它们互动的方式使用时是这样。显然两者都存在，因此您可以链接到另一种类型或声明来交叉链接您的文档（或指向外部链接），但对于与智能感知完成相关的任何内容，这<see />就是您应该使用的。

根据 Microsoft 关于代码内 XML 文档的文档，特别是以下部分seealso：

该<seealso>标签允许您指定可能希望显示在“另请参阅”部分中的文本。用于<see>指定文本内的链接。您不能将seealso标签嵌套在标签内summary。（强调已添加）

看，最初该<see />标签用于交叉引用或链接到您在智能感知补全中看到的正文中的外部资源，并具有完全不同的目的：将链接/脚注添加到生成的 HTML 文档<seealso />的底部，就像那样您可以在页面底部的老式 MSDN 文档中看到。核心标签（您在智能感知弹出窗口中看到的内容）不支持，并且使用旧版本的编译器/旧版本的 Visual Studio，它不会像今天那样呈现。<seealso /><summary>...</summary>

仅限原始<see />用途

以下是一个 xmldoc 示例，该示例使用<see />以及如何在 Visual Studio 中呈现它：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial" />, you cannot configure the lifetime
/// lifetime of this object.
/// </summary>
public class Foo {}

今天，如果使用<seealso />，这也适用，如下所示：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <seealso cref="FooSpecial" />, you cannot configure the
/// lifetime of this object.
/// </summary>
public class Foo {}

如果您要链接到外部内容，而不是在智能感知补全的正文中显示可能又长又笨重的 URL：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.<br/><br/>
/// Refer to this article on managing object lifetimes for more information:
/// <see href="https://neosmart.net/blog/tag/C#"/>
/// </summary>

您可以使用替代符号链接到文本，同时更改显示的内容（就像<a href="..." />HTML 中的标签一样）：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.<br/><br/>
/// Refer to this <see href="https://neosmart.net/blog/tag/C#">
/// article on managing object lifetimes</see> for more information.
/// </summary>
public class Foo { }

原始用途和当前<seealso />用途

前面的所有示例都可以与<see />或 一起正常工作<seealso />，尽管实际规范没有改变，并且从技术上讲，<seealso />以这种方式使用是 100% 错误的，因为它并不意味着嵌套在块中<summary />。

那么<seealso />实际上有什么目的呢？<seealso />尝试遵循 Microsoft 的说明并用作顶级标记是很自然的，并尝试查看它在智能感知中的呈现是否有任何不同：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.
/// </summary>
/// <seealso href="https://neosmart.net/blog/tag/C#">
/// Refer to this article on managing object lifetimes for
/// more information.
/// </seealso>
public class Foo { }

...却发现在 Visual Studio 中查看时它根本不执行任何操作：

但您必须记住，Microsoft 首先提出了他们的 xmldoc 版本，以直接从源文件自动生成 MSDN 文档 - 并非所有 xmldoc 功能都可供智能感知使用。现在，如果您要使用 HTML 文档生成器（我使用了 fxdoc，它最初由 Microsoft 编写，并且仍然以某种方式被他们使用），您将看到以下内容：

的目的<seealso />变得清晰 - 它并不直接有助于对已记录的项目成员（标签summary）的直接描述，但它告诉文档生成器保存<seealso />标签以供以后使用，并在文档的底部发出它“另请参阅”部分的命名非常巧妙！

<seealso>...</seealso>最后一点，如果我看到在最后一个示例中替换为会产生相同的结果，我不会感到惊讶，<see>...</see>因为我假设微软只是决定以相同的方式对待它们，但根据上下文渲染它们（无论它们是否在<summary />块或作为顶级标签），但如果您尝试一下（至少在今天，从 docfx 版本 2.58.9.0 开始），您最终会发现两者之间差异的实际证据：没有“另请参阅”如果<see />用作顶级标签，则会生成部分：

/// <summary>
/// Represents a single item in the internal list.
/// Unlike <see cref="FooSpecial"/>, you cannot configure the lifetime
/// of this object.
/// </summary>
/// <see href="https://neosmart.net/blog/tag/C#">
/// Refer to this article on managing object lifetimes for
/// more information.
/// </see>
public class Foo { }

Answer 2

两者都是经过编译器验证的XML文档标记.

<see> 用于直接在文本中放置链接.

<seealso> 是在"另请参阅"部分中放置文本.

了解它们在此示例中的用法.