XML documentation tags, multiple level inheritance

Question

When using the XML documentation comments in visual studio with methods that are overridden multiple times, I have a problem that some of the text appears twice. An example:

public class TopLevel
{
  /// <summary>
  /// Top level text.
  /// </summary>
  protected virtual void Method() { }
}
public class SecondLevel : TopLevel
{
  /// <summary>
  /// <inheritdoc/>
  /// <para>
  /// Second level text.
  /// </para>
  /// </summary>
  protected override void Method() { }
}
public class ThirdLevel : SecondLevel
{
  /// <summary>
  /// <inheritdoc/>
  /// <para>
  /// Third level text.
  /// </para>
  /// </summary>
  protected override void Method() { }
}

Of course my intention here is to have the tags show up in IntelliSense like this:

Top level text. Second level text. Third level text.

All formatted in their own paragraphs. However, what I get is this:

Top level text. Second level text. Top level text. Third level text.

So, I am seeing the top level text twice. Does anyone know how to prevent this?

Answer 1

Hi,

thank you for the comment and the reply.

I was indeed providing a simplified code example here. I have tried it again with exactly the code I wrote here and it does work. I'm having this problem because in my actual code the overridden method also has a couple of arguments, which I only wanted to describe in the top level method and then use that description in the overrides. What I did to that end was this:

public class TopLevel
{
  /// <summary>
  /// Top level text.
  /// </summary>
  /// <param name="argument1">The first method argument.</param>
  /// <param name="argument2">The second method argument.</param>
  protected virtual void Method(object argument1, object argument2) { }
}
public class SecondLevel : TopLevel
{
  /// <summary>
  /// <inheritdoc/>
  /// <para>
  /// Second level text.
  /// </para>
  /// </summary>
  /// <inheritdoc/>
  protected override void Method(object argument1, object argument2) { }
}
public class ThirdLevel : SecondLevel
{
  /// <summary>
  /// <inheritdoc/>
  /// <para>
  /// Third level text.
  /// </para>
  /// </summary>
  /// <inheritdoc/>
  protected override void Method(object argument1, object argument2) { }
}

I apologize for the confusion.

Writing the second <inheritdoc/> tag after </summary> loads the descriptions of all attributes, which is what I was looking for. In the first overload this ends up as intended, but in the second overload this results in the "Top level text" being displayed twice in IntelliSense.

I have since learned that if I do

/// <param name="argument1"><inheritdoc/></param>
/// <param name="argument2"><inheritdoc/></param>

instead, then the overall result is as intended. Of course this isn't quite as simple as I wanted, is there any way to have the top level descriptions for all arguments loaded with one tag? If not, I can live with this solution as well.

Thanks and best regards

Answer 2

Hi @FlorianL,

Welcome to Microsoft Q&A forum.

I’m not sure if the above example is your real code, but it shows correctly on my side. If it’s your real code, please try to create a new project, and copy the code to this newly created project, and test to see if the IntelliSense shows correctly. If it’s just an example, please kindly check the real code and the XML documentation comments which you wrote.

If the IntelliSense still shows the wrong text, please let us know how you check the IntelliSense.

Feel free to contact us.

Best Regards,

Tianyu

---

If the answer is the right solution, please click "Accept Answer" and kindly upvote it. If you have extra questions about this answer, please click "Comment".

Note: Please follow the steps in our documentation to enable e-mail notifications if you want to receive the related email notification for this thread.