XML文档中的引用操作符

本文关键字：引用 操作符 文档 XML | 更新日期: 2023-09-27 18:18:31

我想在<see cref="..." /> XML文档标记中引用操作符，但我似乎找不到任何关于如何做到这一点的提示。关于这个标签的MSDN文章只展示了一个引用方法的简单示例，但没有详细介绍可以引用的不同类型的成员。

特别地，我想引用隐式转换操作符，但引用操作符的一般规则也将受到赞赏。

<标题> 例子

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

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 };
}

很简单，可以用<see cref="MyStructure.Value" />引用Value属性，但是如何去引用==操作符呢?我显然尝试了<see cref="MyStructure.==" />和<see cref="MyStructure.==(MyStructure, MyStructure)" />，但我不认为这是应该的，因为这两个观察结果:

  1. 在显示摘要的工具提示中不显示操作符的颜色，而不是在正确引用时显示其他成员的颜色
  2. 转到定义命令不起作用，而它对其他正确引用的成员
    3. 起作用
我也怀疑像Sandcastle这样的工具，用来基于XML文档生成HTML页面，也不会产生有效的超链接，但这还有待确认。

编辑

我刚刚确认Sandcastle不会为我的任何尝试产生有效的超链接。此外，当选中在项目属性中生成XML文档的选项时，会显示一个代码为CS1584的警告，说&;XML注释有语法错误的cref属性'MyStructure.=='&;;

<标题>理由h1> 果有人想知道为什么我要引用操作符，答案是我正在编写一个单元测试方法，对操作符执行测试，并且作为一般规则，我将对测试成员的引用放在XML文档中用于测试方法。所以我要找的是: 
/// <summary>
/// This method performs tests regarding <see cref="..." /> operator
/// </summary>
[TestMethod]
public void ImplicitConversionOperator() { ... }

XML文档中的引用操作符

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

<标题> 1。使用生成的方法名

参考这个问题

对于相等运算符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。这些方法可能有多个重载，只是返回类型不同。例如，对于这两个操作符: 
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正确识别，而第一种方法则不能。

我在VS 2015企业…不知道其他版本。看起来，如果你记录你的操作符，你会得到完全正确的行为:

/// <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)"
相关文章：