C# XML documentation '<include>' tag not appearing in intellisense?

user_7144054 0
Viewed 1378

I developing a C# class library in Visual Studio, and I have been making use of XML Documentation Comments primarily for their integration with Intellisense. However, the bulk of comments has become quite cluttered, so now I am endeavoring to use the <include> tag, and an external XML document to reduce the clutter.

My issue is that when using the <include> tag Intellisense seems to not update with the information, not show any of the <summary> and <param> tags that I've assigned to some of my classes and methods.

For Example I could have a class 'Test' documented as shown:

/// <include file="docs.xml" path='extradoc/class[@name="Test"]/*' />
        class Test { string foo = "bar"; }

And have docs.xml:

<?xml version="1.0" encoding="utf-8" ?>
<extradoc>
  <class name="Test">
    <summary>
      Contains some Foo.
    </summary>
  </class>
</extradoc>

And upon build the output XML populates correctly:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>Example Program</name>
    </assembly>
    <members>
        <member name="T:Example_Program.Program.Test">
            <summary>
      Contains some Foo.
    </summary>
        </member>
    </members>
</doc>

The only issue is that, try as I might, this documentation will not appear in the intellisense boxes while appending my code. Is there some Visual Studio configuration setting I'm missing? I've scoured the msn documentation to no avail.

comments intellisense visual-studio xml c#
1 Answers

My issue is that when using the tag Intellisense seems to not update with the information, not show any of the and tags that I've assigned to some of my classes and methods.

1.Avoid that your issue is being not able to see summary in Intellisense in current project A.

You can get help from this document, this technology is used to provide better reading experience. So assuming you have the Test class in current priject A, when you see the content in VS code editor, you'll see something like:

enter image description here

It's expected behavior that you won't see that rich comments in project A any more cause they have been moved to docs.xml.

2.If you mean when you create a new Project B(or share the assembly to other developers), the Intellisense can't recognize your Test class.

Two possible causes:

1.The output xx.dll and xx.xml from project A are not in the same folder, so when you reference that xx.dll in your new project, Intellisense won't display the documentation comments.

2.I guess there's something wrong with your docs.xml file. (I can't find any official document which indicates this technology supports user-defined nodes like extradoc and class in docs.xml, I used these two nodes and the Intellisense did not work, after changing them to normal docs and members, it works now)

Try using docs.xml and include in this way:

<?xml version="1.0" encoding="utf-8" ?>
<docs>
  <members name="MyTests">
    <Test>
      <summary>
        This class is public, but do nothing
      </summary>
      <remarks>
        Just write something here to indicate this is remarks.
      </remarks>
    </Test>
  </members>
</docs>

and 

/// <include file="docs.xml" path='docs/members[@name="MyTests"]/Test/*' />
    public class Test { }

I suggest you use a public class to test... After that create a new project and reference that xx.dll, when calling Test class you can see the summary:

enter image description here

And if we F12 we can see detailed comments:

enter image description here

Hope it helps :)

user_109104500
Related