如何在C#的<seealso>标签中引用方法重载？

Question

我在MSDN中看到了像“CompareOrdinal Overloads”这样的链接。我该如何在C#中编写这样的链接？

我尝试过：

<seealso cref="MyMethod">MyMethod Overloads</seealso>

但编译器给我一个警告，说这个方法是模棱两可的引用，而这个方法有其他重载。

（初学者问题：我是否需要编写此标记来链接到重载，还是它会被文档处理器自动生成？）

- Hosam Aly

Answer 1

要针对特定的成员，我认为你只需要匹配签名即可：

/// <seealso cref="Foo(int)"/>
static void Foo() { }
/// <seealso cref="Foo()"/>
/// <seealso cref="Foo(float)"/> <------ complains
static void Foo(int a) { }

说实话，我不确定如何生成"所有重载"的链接；我认为任何明智的生成器都会自动完成这个任务。

- Marc Gravell

---

谢谢。您使用的生成器是否会自动执行此操作？ - Hosam Aly

我实际上不使用生成器；对于我的用途，仅使用 XML 就足够了（它由Intellisense和Reflector都使用）。 我通常不需要独立的文档。 - Marc Gravell

Answer 2

使用Sandcastle非常简单：

<seealso cref="overloads:FullyQualifiedMyMethod">MyMethod Overloads</seealso>

FullyQualifiedMyMethod是完整的路由，包括命名空间和类，例如：System.Linq.Enumerable.Sum。

然而VB编译器会发出警告，说无法解析该属性，但可以忽略该警告。

- Wilhelm

---

通过使用SHFB 2014.5.31.0进行测试，发现前缀必须为o:而不是overloads:。 - tm1

C#编译器（已测试语言版本5.0）在使用o:时不会发出警告，因此这可能是可行的方法。 - binki

尝试过使用 "see"（而不是 "seealso"）但完全没有运气。重载：发出编译器警告，SHFB 14.5.31忽略它。还尝试了 o: 和 M:，编译器可以通过，但 SHFB 两者都忽略。 - Doug Clutter

我想说这应该是被接受的答案，但是OP没有指定Sandcastle，所以，嗯...也许不是。仍然非常有用+1。 - AnorZaken

遇到了引用重载页面的问题，但最终我找到了正确的语法：对我有效的是使用大写字母'O'、方法的完整名称和不带括号的方式，如下所示：<see cref="O:My.Long.Namespace.Class.Method">Link name</see>。 - Anders

Answer 3

Xml文档没有一种方法可以引用方法的所有重载。

C#项目中最受欢迎的文档生成器是Sandcastle。如果需要，它将自动创建指向重载列表页面的链接。因此，在成员列表页面上，重载方法的名称只会出现一次，单击它将导航到该方法的重载列表页面，然后再导航到特定的重载。

在Xml文档中放置指向重载列表页面的链接需要对使用的外部工具有深入的了解，可能不是个好主意。

如果您真的需要这个功能，那么也许一种方法是使用带有特定格式ID的锚点。大多数文档生成器提供某些奇怪的预处理或后处理生成文件的方法，并应该为您提供选择这些锚点并为其提供适当href的机会。

另一方面，这可能比它值得的麻烦多了 ;)

- AnthonyWJones

---

沙堡的行为应该对我足够了。谢谢信息。 - Hosam Aly