Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

XML Comments -- How do you comment explicitly implemented interfaces properly?

Code:

public interface IFoo
{
    void Bar();
}

public class FooClass : IFoo
{
    /// <summary> ... </summary>
    /// <seealso cref="?"/> //How do you reference the IFoo.Bar() method
    public void Bar() { }

    /// <summary> ... </summary>
    /// <seealso cref="?"/> //How do you reference the standard Bar() method
    void IFoo.Bar() { }
}

My guess is:

<seealso cref="IFoo.Bar()"/> //Explicitly implemented interface method
<seealso cref="Bar()"/>      //Standard method

but, I'm not sure. The ECMA guide didn't help distinguish, so I guess I'm looking for assurance that my guess is correct.

like image 866
myermian Avatar asked May 14 '11 12:05

myermian


People also ask

Which is the proper commenting method for XML?

To insert XML comments for a code element Type /// in C#, or ''' in Visual Basic.

How do I enable XML comment analysis?

Enabling XML Comments XML comments are enabled by default in Visual Basic projects, and cannot be disabled. To enable or disable XML comments for a specific project, go to the project properties page, the Compile tab, and update the "Generate XML documentation file" checkbox.

What is XML documentation in C#?

The C# compiler combines the structure of the C# code with the text of the comments into a single XML document. The C# compiler verifies that the comments match the API signatures for relevant tags. Tools that process the XML documentation files can define XML elements and attributes specific to those tools.

How do I make comments in Visual Studio?

The only way I know to do this is on the line right above your method just type "///" and it will generate a comment template based on the method.


1 Answers

A quick test with Sandcastle Help File Builder revealed that in the created documentation the link <seealso cref="IFoo.Bar()"/> points to the method in the interface and <seealso cref="Bar()"/> points to the method in the class. The documentation for the explicitly implemented method is inherited from the interface so you should actually point to the interface method anyway.

Edit: ReSharper also complains with <seealso cref="FooClass.IFoo.Bar()"/> and corrects it to be <seealso cref="IFoo.Bar()"/> which then points to the interface method, not the explicitly implemented one.

like image 50
Teoman Soygul Avatar answered Oct 11 '22 20:10

Teoman Soygul