How do you handle the inclusion of examples into your C# documentation ? If you've been asking yourself this question, here's a quick tip for automatic example inclusion.
Let's start with an example. Consider the following dummy class MyClass:
public class MyClass { ... }
We hapilly write anexample for the MyClass class in a separate xml file (say Doc.xml):
<doc> <examples> <example name="example1"> public class MyLibrary { public static Main(string[] args) { MyClass mc = new MyClass(); } } </example> </examples> </doc>
Now the way Visual Studio suggests uses to include the example is to use the include tag with a XPath expression similar to this:
//< include file='Doc.xml' path='example[@name="example1"]' />
This is fine but it can break easily.Moreover, assuming that you have a lots of examples, you may miss some example that could be integrated into the documentation.
A much better solution is to use the power of XPath. In fact, what we want to include is all the examples that involve the MyClass class, which in XPath translates to: contains(descendant-or-self::*,'MyClass'):
/// <include /// file='MyLibrary.Doc.xml' /// path='//example[contains(descendant-or-self::*,"MyClass")]' /// />
That's it. Instead of using name=... you stop worrying and let XPath find the proper examples for you.
Page rendered at Thursday, December 04, 2008 9:00:29 AM UTC
Disclaimer The opinions expressed herein are my own personal opinions and do not represent my employer's view in anyway.