实施例

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引用<see cref="MyStructure.Value" />属性，但是如何引用==运算符？我显然尝试<see cref="MyStructure.==" />和<see cref="MyStructure.==(MyStructure, MyStructure)" />，但我不认为这可以正常运作，因为这两个观察结果：

操作员在显示摘要的工具提示中没有着色，而正确引用时其他成员被着色
转到定义命令不起作用，而它适用于其他正确引用的成员

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

修改

我刚刚确认 Sandcastle 没有为我的任何尝试生成有效的超链接。此外，当选中在项目属性中生成 XML文档的选项时，会显示代码为 CS1584 的警告，说明＆＃34; XML注释在语法上不正确的cref属性＆＃39; MyStructure。==＆＃39; ＆＃34;。

理由

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

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

Answer 1

我参加了VS 2015 Enterprise ... dunno＆＃39;其他版本。看起来，如果您记录您的操作员，您将获得完全正确的行为：

/// <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)" />

这种方法有一个缺点（据我所知）。对于转换运算符，方法名称分别为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 正确识别，而第一种方法则没有。

XML文档中的引用运算符

实施例

理由

2 个答案:

1。使用生成的方法名称

2。使用 C＃运算符名称

其他注意事项