Code snippets

Topics: Developer Forum, Project Management Forum, User Forum
Jun 5, 2014 at 9:58 AM

Is this possible to use code snippet files in SHFB to inject code samples in the reference documentation ?
For example, in the snippet file we could format the item id a certain way so that it detects the code entity associated with the code example ?

Or maybe it can be done another way ?

My goal is to inject the code example in the generated documentation and be able to reuse it in the conceptual content easily.

Jun 5, 2014 at 3:17 PM
The code element in both MAML and XML comments has been extended to support code importing (whole file or region). It's more flexible than the MAML codeReference element and lets you import code from buildable projects so you can ensure it's valid. Use the source attribute to specify the file to import and the region attribute to limit the import to a specific region if needed. Relative paths are supported on the source attribute and are assumed to be relative to the SHFB project's location.

Jun 5, 2014 at 3:35 PM
Thanks, is there a way to import code given an xpath expression ?

I find it not easy to share code examples between reference content and conceptual content.

The more i think about it, the more it makes sense to put the code examples in the csproj, but then i don't see how i can access these from the conceptual content.

What would you recommend for this scenario ?
Jun 5, 2014 at 7:30 PM
If you want to use an XML file and XPath, you need to use an include element but that's only valid from XML comments. As I mentioned above, use the source and region attributes on the code element to import code from a file. That method works in both XML comments and conceptual topics and is used identically in both.

Jun 5, 2014 at 9:57 PM
That's the way I do it now, using the include element.
In my csharp projects I have an examples folder where I store one XML file per documented class containing the examples for that class.
The advantage is that I can reference the same example from several XML comment places using the appropriate xpath query.
Usually I have one or more example per method, and at the class level I include all examples for all the methods of the class.

It works well. The only problem is that I can't access these examples in the conceptual topics, I hoped there was a way to access the XML generated by the compiler in some way. In fact I don't need to access the example file itself, extracting the example node in generated XML would be fine as I know the code entity reference I want to access.

Is there a way to access the XML documentation source from a conceptual topic ?

Jun 6, 2014 at 2:08 AM
You can write a build component that handles a custom include element in conceptual topics but it would largely be doing what the code block component is doing already but with XPath queries instead.