Question

I am trying to use the <code> tag inside the <example> tag to show a sample code in xml documentation. However, when I build the Sandcastle project, I see that it is shown as C#. There is no language attribute in <code> tag. And I could not find a setting in Sandcastle’s project properties. Am I missing something?

BTW, I am using HtmlHelp1 format.

Answer 1

Actually, if you move beyond Sandcastle to Sandcastle Help File Builder (SHFB),
you will get both an easier to use interface to Sandcastle and additional features for your documentation set, including just what you want: a language attribute (language) for the <code> element.

Note that SHFB generates a language selector menu but that only lets you
show or hide a particular set of languages (C#, VB.NET, C++, J#, JScript.NET, XAML, and JavaScript). It supports colorizing, though, of a larger set (C#, VB.NET, JScript.NET, C++, J#, C, JavaScript, VBScript, XAML, XML, HTML, SQL script, PowerShell script, and Python). (From the Code Block Component section of the SHFB documentation.)

I have written extensively on this point, as well as many other tips and pitfalls of Sandcastle and SHFB, in my article Taming Sandcastle: A .NET Programmer’s Guide to Documenting Your Code published on Simple-Talk.com. Besides the main article, I also put together a wallchart/quick reference that gives you everything you need to know to use Sandcastle/SHFB on one page–the link also appears at the end of the article.

You can find more details about the <code> element in the Displaying Sample Code section of my article, as well as from the official SHFB documentation at Importing and Colorizing Code from Source Files.