XML documentation , but I cannot find any ...">
Geek Answers Handbook

Reference operators in XML documentation

I would like to refer to the operator in the <see cref="..." /> XML documentation , but I cannot find any hints on how to do this. The MSDN article in this tag shows only a simple example that refers to a method, but does not affect the various types of members that can be referenced.

In particular, I would like to refer to the implicit conversion operator , but a general rule for link operators will also be adopted.

Example

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

It is enough to simply refer to the Value property on <see cref="MyStructure.Value" /> , but how to access the == operator? I obviously tried <see cref="MyStructure.==" /> and <see cref="MyStructure.==(MyStructure, MyStructure)" /> , but I don't think this works as it should from due to these two observations:

  • The operator is not colored in a tooltip showing a summary, unlike other elements colored with the correct link.
  • The Go to definition command does not work, while for other duly appointed members

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

EDIT

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

Justification

If someone wonders why I want to refer to an operator, I write a unit test method that runs tests for the operator, and as a general rule I put references to the test members in the XML documentation for the test method. So what I need is:

 /// <summary> /// This method performs tests regarding <see cref="..." /> operator /// </summary> [TestMethod] public void ImplicitConversionOperator() { ... }
+7
c # xml-documentation
source share
2 answers

I'm on VS 2015 Enterprise ... I don't know any other releases. It seems that if you document your statement, you will get the full 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 highlights all the functionality of the IDE (except that it does not appear in the participants drop-down list):

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

The Go-to feature also works here.

Edit:

Implicit statement:

 <see cref="MyStruct.op_Implicit(int)"
+3
source share

To clarify @Clay's answer - there are two ways (I know) of links to links in the <see (...)/> XML documentation tag:

1. Using the names of the generated methods

See this question for reference.

For equality bool operator ==(MyStructure x, MyStructure y) link

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

For an implicit conversion implicit operator MyStructure(int i) is

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

However, there is a drawback to this approach (as far as I can tell). For conversion operators, the op_Implicit and op_Explicit method names for the implicit and explicit statements, respectively. It is possible to have several overloads of these methods that differ only in the return type. For example, 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 link:

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

will be ambiguous, and it will depend on which operator is defined first. You will also receive a warning saying just that.

2. Using C # Operator Names

For equality bool operator ==(MyStructure x, MyStructure y) link

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

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

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

Obviously, there is no problem in disambiguating the previously mentioned example:

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

Other considerations

Another difference that I noticed is that the second approach is correctly recognized by CodeLens, while the first is not.

+2
source share

More articles:


All Articles