Can someone help a newb?

Feb 20, 2008 at 3:30 PM

I just started using Sandcastle, and so far it's working great for what I need. However I've got a few questions I hope someone can answer. I'm trying to document a class I've written in C# using the triple slash XML comments, and I've run into some things that I can't seem to find the answer for.

First, in one of my <code> blocks I'm trying to document a web.config or app.config snippet, so I'm actually trying to embed XML tags into the code block. In order to get it to render correctly, I had to use the HTML character code for the angle brackets in my snippet in order for it to generate the code block correctly. Is this the only way to accomplish something like this, or is there a better way?

Second, since the aforementioned code block actually contains XML, not C# code, is there a way to get the heading above the block in my help doc to say "XML" (or better still "web.config or app.config") rather than "C#"?

Third, on the class members help page, my Item property's description merely says "Overloaded.". While this is OK because when you click through to the overload list the <summary>'s for each overload are correct, I'd really like it to say more, just like it does on MSDN for the NameValueCollection's Item property on its members help page(go here and check out the description for the Item property to see what I'm talking about).

Thanks to all that can help.
Feb 20, 2008 at 4:12 PM
Edited Feb 20, 2008 at 4:28 PM
See this thread for solutions to items 1 and 2:

If you're already using SHFB (I'm assuming you are due to the default C# title), you can add a lang attribute to the <code> block to identify the language which will then default the title to the language or you can specify a title attribute to supply a different title. See the Code Block Component documentation in the help file for details.

For the third item, add an <overloads> tag containing the text you want to appear to one of the methods. For the Hana and VS2005 styles, it will appear on the summary page after the "Overloaded." text.

Feb 20, 2008 at 4:40 PM

For the third issue, Eric's suggestion is already part of Sandcastle.

For example:

/// <overloads>
/// <summary>This is the overloads summary.</summary>
/// </overloads>
/// <summary>Summary for the first overload.</summary>
public void OverloadMe();
/// <summary>Summary for the second overload.</summary>
public void OverloadMe(bool arg);
You should then see, "Overloaded. This is the overloads summary." in pseudo topics; e.g., All Members and Methods.

- Dave
Feb 22, 2008 at 2:51 PM
Ewoodruff & davedev,

Thanks for the help, it's much appreciated. EWoodruff, you are correct in your assumption that I'm using SHFB.

Work's picked up so I can't implement your suggestions now, but I'll report back when I get a free moment on if I'm successful.