Grx70 Grx70 - 15 days ago 6
C# Question

Reference operators in XML documentation

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.




Example



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


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. 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



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.

EDIT

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.=='".




Justification



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() { ... }

Answer

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

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.

Edit:

Implicit operator is:

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