XML文档中的引用运算符 [英] Reference operators in XML documentation

问题描述

我想在< see cref =".../> XML文档标记，但是我可以似乎找不到任何提示.此标签上的 MSDN文章仅显示了引用方法的简单示例，但不会遍历可以引用的不同类型的成员.

I would like to reference an operator in a <see cref="..." /> XML documentation tag, but I can't seem to find any hints on how to do it. The MSDN article on this tag only shows a simple example referencing a method, but does not go over different types of members that can be referenced.

特别是，我想引用隐式转换运算符，但也应理解引用运算符的一般规则.

In particular, I would like to reference an implicit conversion operator, but general rule for referencing operators will also be appreciated.

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

Let's say we have a simple structure for which we define ==, != and implicit conversion operators:

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 属性即可，请参见cref ="MyStructure.Value"./> ，但是如何引用 == 运算符?我显然尝试了< see cref ="MyStructure.=="/> 和<参见cref ="MyStructure.==(MyStructure，MyStructure)"/> ，但由于以下两个原因，我认为此方法无法正常工作:

Simply enough one can reference the Value property with <see cref="MyStructure.Value" />, but how to go about referencing the == operator? I obviously tried <see cref="MyStructure.==" /> and <see cref="MyStructure.==(MyStructure, MyStructure)" /> but I don't think this works as it should because of these two observations:

1. 在工具提示中，操作员没有显示摘要的颜色，与正确引用其他成员时不同的是
2. 转到定义命令不起作用，而对其他引用正确的成员则起作用

1. The operator is not coloured in the tooltip showing a summary as opposed to other members being coloured when properly referenced
2. The Go to definition command does not work whereas it does for other properly referenced members

我还怀疑 Sandcastle 之类的工具可用于根据 XML文档也不会产生有效的超链接，但这仍有待确认.

I also suspect tools like Sandcastle used to generate HTML pages based on the XML documentation would not produce valid hyperlinks either, but that remains to be confirmed.

编辑

我刚刚确认 Sandcastle 对于我的任何尝试都不会产生有效的超链接.此外，当选项生成的 XML文档在项目属性被选中时，与代码警告的 CS1584 示说" XML注释在语法上具有不正确的cref属性"MyStructure.=='"".

I just confirmed that Sandcastle does not produce valid hyperlinks for any of my attempts. Also, when the option to generate the XML documentation in the project properties is checked, a warning with code CS1584 is shown saying "XML comment has syntactically incorrect cref attribute 'MyStructure.=='".

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

In case someone is wondering why do I want to reference an operator the answer is I am writing a unit test method performing tests on an operator and as a general rule I put references to tested members in the XML documentation for the test method. So what I'm after is this:

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

推荐答案

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

I'm on VS 2015 Enterprise...dunno 'bout other editions. It looks like, if you document your operator, you get full-on correct behavior:

/// <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功能亮起(除了成员下拉列表中未显示):

Then, to reference, this works and lights up with all the IDE functionality (except that it doesn't show in the member drop-down):

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

转到此处的功能也起作用.

Go-to functionality works here, too.

隐式运算符为:

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

这篇关于XML文档中的引用运算符的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！