19

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() { ... }
Improve this question
3
  • From here, it looks like you can use: <see cref="M:MyStructure.Operator==(a,b)"/>. I tried it and it compiles w/o warning...and makes it into the XML. IDE behavior is still incomplete. Commented Nov 19, 2016 at 12:03
  • @Clay You're right about the warning being gone, but unfortunately other concerns are still unresolved. It seems that putting M: in front (or any other letter followed by colon) lets you put almost anything after it without the warning - e.g. <see cref="x:whatever"/> does not raise the warning. Strangely enough, two letters and a colon does not fly... Commented Nov 19, 2016 at 12:54
  • Yeah - I was playing with it. Seems like M means maybe. Commented Nov 19, 2016 at 13:04

2 Answers 2

Reset to default
12

To elaborate on @Clay's answer - there are two ways (that I know of) of referencing operators in the <see (...)/> XML documentation tag:

1. Using generated method names

See this question for reference.

For the equality operator bool operator ==(MyStructure x, MyStructure y) the reference is

<see cref="MyStructure.op_Equality(MyStructure, MyStructure)" />

For the implicit conversion operator implicit operator MyStructure(int i) it is

<see cref="MyStructure.op_Implicit(int)" />

There is however a drawback to this approach (as far as I can tell). For conversion operators the method names are op_Implicit and op_Explicit for implicit and explicit operators respectively. It is possible to have several overloads of these methods differing only by the return type. For instance, for these two operators:

public static implicit operator int(MyStructure s) => s.Value;
public static implicit operator double(MyStructure s) => s.Value;

these methods will be generated:

int op_Implicit(MyStructure)
double op_Implicit(MyStructure)

Then this reference:

<see cref="MyStructure.op_Implicit(MyStructure)" />

will be ambiguous, and it will fallback to whichever operator is defined first. You'll also get a warning saying just that.

2. Using C# operator names

For the equality operator bool operator ==(MyStructure x, MyStructure y) the reference is

<see cref="MyStructure.operator ==(MyStructure, MyStructure)" />

and for the implicit conversion operator implicit operator MyStructure(int i):

<see cref="MyStructure.implicit operator MyStructure(int)" />

Obviously there's no problem in disambiguating previously mentioned example:

<see cref="MyStructure.implicit operator int(MyStructure)" />
<see cref="MyStructure.implicit operator double(MyStructure)" />

Other considerations

One other difference that I've noticed is that the second approach is properly recognized by CodeLens, whereas the first one is not.

Improve this answer
Sign up to request clarification or add additional context in comments.

Comments

8

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)"
Improve this answer

3 Comments

Good catch, that does work indeed! Any thoughts on the conversion operator though?
@Grx70, I edited the answer...just looked up what the XML output was on the member :-)
Basing on your answer I've played around with it for a while and posted my findings as an alternative answer.

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge you have read our privacy policy.

Start asking to get answers

Find the answer to your question by asking.

Ask question

Explore related questions

See similar questions with these tags.