c# - XML 文档中的引用运算符

Question

我想在 <see cref="..." /> 中引用一个运算符XML documentation标签，但我似乎找不到任何关于如何操作的提示。 MSDN article在这个标签上只展示了一个引用方法的简单例子，并没有涉及可以引用的不同类型的成员。

特别是，我想引用一个隐式转换运算符，但也欢迎引用运算符的一般规则。

---

例子

假设我们有一个简单的结构，我们为其定义了 == , !=和隐式转换运算符:

public struct MyStructure
{
    public int Value { get; set; }

    public static bool operator ==(MyStructure x, MyStructure y) => x.Value == y.Value;

    public static bool operator !=(MyStructure x, MyStructure y) => x.Value != y.Value;

    public static implicit operator MyStructure(int i) => new MyStructure { Value = i };
}

很简单，可以引用 Value属性(property) <see cref="MyStructure.Value" /> , 但如何引用 ==运算符(operator)？我显然试过了 <see cref="MyStructure.==" />和 <see cref="MyStructure.==(MyStructure, MyStructure)" />但由于以下两个观察结果，我不认为这是应该的:

1. 运算符在显示摘要的工具提示中没有着色，而其他成员在正确引用时被着色
2. Go to definition 命令不起作用，而它对其他正确引用的成员起作用

我还怀疑像 Sandcastle 这样的工具用于生成基于 XML 文档 的 HTML 页面也不会生成有效的超链接，但这仍有待确认。

编辑

我刚刚确认 SandcaSTLe 不会为我的任何尝试生成有效的超链接。此外，当在项目属性中生成 XML 文档 的选项被选中时，将显示代码为 CS1584 的警告，内容为“ XML 注释具有句法不正确的 cref 属性“MyStructure.==””。

---

理由

如果有人想知道我为什么要引用运算符，答案是我正在编写一个单元测试方法，对运算符执行测试，并且作为一般规则，我将对测试成员的引用放在 XML 文档 用于测试方法。所以我追求的是:

/// <summary>
/// This method performs tests regarding <see cref="..." /> operator
/// </summary>
[TestMethod]
public void ImplicitConversionOperator() { ... }

Answer 1

详细说明@Clay 的回答 - 在 <see (...)/> 中有两种引用运算符的方式(据我所知) XML 文档标签:

1。使用生成的方法名

参见 this question供引用。

对于相等运算符 bool operator ==(MyStructure x, MyStructure y)引用是

<see cref="MyStructure.op_Equality(MyStructure, MyStructure)" />

对于隐式转换运算符implicit operator MyStructure(int i)这是

<see cref="MyStructure.op_Implicit(int)" />

但是这种方法有一个缺点(据我所知)。对于转换运算符，方法名称是 op_Implicit和 op_Explicit对于 implicit和 explicit运营商分别。这些方法的多个重载可能仅在返回类型上有所不同。例如，对于这两个运算符:

public static implicit operator int(MyStructure s) => s.Value;
public static implicit operator double(MyStructure s) => s.Value;

将生成这些方法:

int op_Implicit(MyStructure)
double op_Implicit(MyStructure)

然后这个引用:

<see cref="MyStructure.op_Implicit(MyStructure)" />

将是不明确的，它将回退到首先定义的操作符。您还会收到一条警告。

2。使用 C# 运算符名称

对于相等运算符 bool operator ==(MyStructure x, MyStructure y)引用是

<see cref="MyStructure.operator ==(MyStructure, MyStructure)" />

对于隐式转换运算符 implicit operator MyStructure(int i) :

<see cref="MyStructure.implicit operator MyStructure(int)" />

显然，消除前面提到的示例的歧义没有问题:

<see cref="MyStructure.implicit operator int(MyStructure)" />
<see cref="MyStructure.implicit operator double(MyStructure)" />

其他注意事项

我注意到的另一个区别是，CodeLens 可以正确识别第二种方法，而第一种则不能。