C#在Visual Studio 2010中，XML标签"see"和"seealso"的含义是什么？

Question

当您在Visual Studio 2010中工作并在方法上撰写评论时，单击Enter键。Visual Studio 2010允许您创建“see”和“see also”XML注释。

如果您在评论中键入“see”并按下TAB键，则会显示如下内容：

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

在C#中，it的含义是什么？

- Steven Spielberg

---

这实际上不是C#的一部分，而是默认的 .Net 文档标准之一。 - Dykam

三个反斜杠是C#语法。 - Philip Smith

@Philip：不，只有前两个是C#。只是VS语法着色使其看起来不同而已。 - H H

@Henk - 在VB中，您使用三个单引号。因此，三个反斜杠是特定于C＃的。 - Philip Smith

/ 表示正斜杠。 \ 表示反斜杠。 - zimdanen

Answer 1

<see />和<seealso />最初是完全不同的标记，用于完全不同的目的，但今天（也许是为了认识到情况有多么令人困惑），它们在使用时几乎是相同的，至少是大多数人与它们交互的方式。显然，两者都存在，以便您可以链接到另一种类型或声明，以跨链接您的文档（或指向外部链接），但对于任何与Intellisense完成相关的内容，您应该使用<see />。

根据Microsoft有关代码中XML文档的文档，特别是seealso的部分：

“<seealso>标记可让您指定可能希望出现在“请参阅”部分中的文本。<see>用于指定从文本内部链接。您无法将seealso标记嵌套在summary标记内。”（强调添加）

看，最初<see />标记用于在intellisense完成中的正文中进行交叉引用或链接到外部资源，而<seealso />则具有完全不同的目的：在生成的HTML文档（例如在旧式MSDN文档底部看到的那样）中添加链接/脚注。<seealso />不受核心<summary>...</summary>标记（在intellisense弹出窗口中看到的内容）的支持，在旧版本的编译器/旧版本的Visual Studio中，它不会呈现今天的方式。

仅使用原始<see />

这是一个使用<see />的xmldoc示例及其在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>

你可以使用替代符号来链接文本并改变显示的内容（就像HTML中的<a href="..." />标签）：

/// <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 />正常工作，尽管实际规范没有改变，但在<summary />块中嵌套<seealso />是100％错误的，因为它不是用于此目的。

那么<seealso />到底有什么作用呢？自然而然地，我们会遵循Microsoft的指示，并将<seealso />作为顶级标记使用，并尝试查看它是否以不同的方式呈现在Intellisense中：

/// <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中查看时什么也没有发生： 但是您必须记住，微软最初推出了他们的版本的xmldoc以直接从源文件自动生成MSDN文档 - 并非所有xmldoc功能都适用于智能感知。现在，如果您使用HTML文档生成器（我使用了fxdoc，这是由Microsoft最初编写的，并且仍然被他们某些方式使用），您将看到以下内容：

<seealso />的目的很明显——它并不直接为文档项目成员（summary标签）的立即描述做出贡献，但它告诉文档生成器将<seealso />标签保存起来，并在文档底部以“参见”部分的形式发出！最后需要注意的是，如果您在最终示例中用<see>...</see>替换<seealso>...</seealso>，可能会生成相同的结果，因为我认为Microsoft决定将它们视为相同，但根据上下文（是否在<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 { }

- Mahmoud Al-Qudsi

---

感谢 @Mahmoud Al-Qudsi 提供如此好的、有用的解释。 - Nicolae

这是一个非常深入的回答。非常感谢！ - cyber_angel

Answer 2

这两个都是XML文档标签，可以由编译器验证。

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

<seealso>用于将文本放置在“另请参阅”部分。

可以参考此示例来了解它们的使用方法。

- Oded

---

我们仍然缺少一个有意义的例子来说明它们之间的差异。提供的链接示例只是表明 <see> 生成一个 XML 元素，而 <seealso> 则生成另一个。 - LosManos

对于那些点击了“此链接”却得到404错误的人，这里有一个新链接。 - Arthur Edgarov

这个例子怎么样？由于不能使用两次 see，我们可以使用 seealso 来创建类似下面的内容：<returns> 一个 <see cref="Task">Task<<seealso cref="bool"></seealso>></see>。 </returns> - Zunair

Answer 3

根据.NET xml文档标准，See和SeeAlso会转换为对其他类的引用，显示在生成的文档中。

请阅读http://msdn.microsoft.com/en-us/library/5ast78ax.aspx以了解更多可用标签的信息。

请注意，除此之外，Sandcastle还支持子类上的<inheritdoc/>标签，将基类的文档复制到子类中。

- TomTom

Answer 4

很久以来，我很惊讶没有人回答这个问题最重要的部分。

Microsoft的标准文档系统是由特殊的注释标记（///或'''或---等，具体取决于语言）驱动的。

默认情况下，该系统仅提供智能感知。在编译期间从这些特殊注释和其中支持的任何标签创建的XML输出可以用作其他系统（如SandCastle和DocFX）的输入，但您必须安装这些工具并配置它们才能从中受益。如果使用此类工具，则两个标记之间的区别由工具和可能的配置方式而不是由Microsoft确定。因此，请阅读有关所涉及工具的文档，以了解标记是否被不同地处理，如果是，以何种方式处理。

话虽如此，如果您不使用外部工具，则可能看不到使用任一标记的意义，因为没有明显的理由这样做，如果选择使用其中一个标记与使用另一个标记之间也没有明显的区别。

事实上，从智能感知的角度来看，目前它们之间没有区别。然而，即使您不使用读取XML输出的工具，使用其中一个标记仍有非常好的理由，那就是“重构”！

通过将标识符（使用see或seealso）标记化，而不仅仅是将其名称键入为字面文本，Visual Studio的重构工具会被告知该标签是合法的标识符。这导致对标识符进行任何重命名时都包括标记内容。与在标识符重命名时必须进行模糊的字符串搜索以使文档与源代码同步相比，这具有巨大优势。

在某种程度上，它具有类似于nameof（）运算符的功能，后者用于构建字符串。不同之处在于，它适用于任何特殊标记的注释中，而不是在代码中。

- bielawski

Answer 5

这些元素用于文档创建。如果您查看MSDN，您会发现在类描述中有几个链接指向其他类型。

编辑 请参考http://www.sandcastledocs.com/作为创建这些帮助文件的示例应用程序。

- Florian Reischl