XML 文档中的参考运算符

Question

我想在<see cref="..." />中引用一个运算符 XML documentation tag, but I can't seem to find any hints on how to do it. The 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 属性和 <see cref="MyStructure.Value" />，但是如何引用 == 运算符呢？我显然尝试了 <see cref="MyStructure.==" /> 和 <see cref="MyStructure.==(MyStructure, MyStructure)" />，但由于以下两个观察结果，我认为这并不能正常工作：

运算符在显示摘要的工具提示中没有着色，这与其他成员在正确引用时着色相反
转到定义 命令不起作用，而它对其他正确引用的成员有效

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

编辑

我刚刚确认 Sandcastle 没有为我的任何尝试生成有效的超链接。此外，当在项目属性中生成 XML 文档 的选项被选中时，代码为 CS1584[=61= 的警告] 显示为“XML 注释的 cref 属性语法不正确 'MyStructure.=='”。

理由

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

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

Answer 1

我使用的是 VS 2015 Enterprise...不知道其他版本。看起来，如果您记录您的操作员，您将获得完全正确的行为：

/// <summary>The name sez it all</summary>
public struct MyStruct
{
  /// <summary>implicit</summary>
  /// <param name="i">an int</param>
  public static implicit operator MyStruct( int i )
  {
    return new MyStruct( );
  }
  /// <summary>Thus and so</summary>
  public static bool operator ==( MyStruct a, MyStruct b )
  {
    return false;
  }

  /// <summary>Thus and so</summary>
  public static bool operator !=( MyStruct a, MyStruct b )
  {
    return true;
  }

  /// <summary>Thus and so</summary>
  public override bool Equals( object obj )
  {
    return base.Equals( obj );
  }

  /// <summary>Thus and so</summary>
  public override int GetHashCode( )
  {
    return base.GetHashCode( );
  }

  /// <summary>Thus and so</summary>
  public override string ToString( )
  {
    return base.ToString( );
  }
}

然后，作为参考，它可以工作并点亮所有 IDE 功能（除了它没有显示在成员下拉列表中）：

/// <summary>
/// See <see cref="MyStruct.operator=="/>
/// </summary>
[StructLayout( LayoutKind.Sequential )]
internal struct BY_HANDLE_FILE_INFORMATION
{
   //...
}

Go-to 功能也适用于此。

编辑：

隐式运算符是：

<see cref="MyStruct.op_Implicit(int)"

Answer 2

详细说明@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)" />

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

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 正确识别，而第一种则不能。

XML 文档中的参考运算符

Reference operators in XML documentation

.net

c#

xml-documentation

例子

理由

1。使用生成的方法名称

2。使用 C# 运算符名称

其他注意事项