1

I am trying to declutter my classes that contain a fair amount of code. I want to also document and document well. Unfortunately for me to do this all in one file creates chaos for the eyes personally. It's gross and for quick developing it creates mass amounts of unnecessary eye catching text to comb through.

<include> seemed promising to achieve this, while maintaining intellisense functionality. Ie the included Xml documentation summary would show in the tooltip, just as it does if the Xml documentation was declared right above the method.

Perhaps I misunderstood <include>, but I did this and the tooltip did not include the Xml documentation that was in the other file.

Here is how I have it setup now:

/// <include file='xml_include_tag.xml' path='include/member[@name="Foo"]/*' />
private String Foo()
{
    return "Foo";
}

The Xml file looks like this:

<include>

    <member name="Foo">
        <summary>
            Returns "Foo"
        </summary>
        <returns></returns>
   </member>

</include>

Am I using this correctly or is this not even possible to achieve with the provided toolset?

Thanks in advance!

David Carrigan
  • 751
  • 1
  • 8
  • 21
  • This is one reason why I only ever use the `` tag and put everything the in there :P – Cameron Feb 05 '15 at 17:33
  • @Cameron ditto. It's nice they organize info seperately like exception info, remarks etc can be extremely helpful. But 10+ lines of xml for every method? It's a bit much Lol If include worked this way we could also share documentation across methods which would be nice to. – David Carrigan Feb 05 '15 at 17:44

1 Answers1

0

The documentation is not entirely clear, but it appears that this feature is not supported by IntelliSense in the Visual Studio C# editor (at least, in VS2013). Too bad, it seems useful.

Instead, it seems to work only with the "XML documentation file" option in the project properties (Build section), which outputs the expected XML.

Note that your XML file does not quite match the XPath statement -- you need a root element named <include> wrapped around the <member> element for it to match.

Cameron
  • 96,106
  • 25
  • 196
  • 225
  • That's odd because I included the root tag but it gets removed when saved. However it is there in the Xml file but still no luck. I was also afraid of this to. That it only applies to the output documents, nothing internal with IntelliSense, shucks. – David Carrigan Feb 05 '15 at 19:27