What is the proper way to reference Embedded Resources in .net xmldoc comments?

Question

I have a C# project that uses xml comments. I make chm files from them with Sandcastle via the Sandcastle Help File Builder. One of the member functions in this project makes use of an embedded resource. I want to reference it in the help file. It seems that sandcastle does not support this, but the xml documentation files it parses does. I say this because of the following example

/// <summary>
/// Displays the resource text.
/// </summary>
/// <remarks>The file is loaded from the <see cref="Resources.TextFile.txt"/>.</remarks>
private static void ShowResource()
{
    // Getting text from embedded resource
}

If I compile that code and compile a chm from the resulting xml documentation I get the following in the build log:

  Warn: CachedResolveReferenceLinksComponent: Unknown reference link target '!:Resources.HelpTextFile.txt'.

And the remarks section is:

The help file is loaded from the [!:Resources.TextFile.txt].

If I do as Agent Smith for ReSharper suggests and change the <see/> element to <see cref="Resources.TextFile"/> the build log says:

Warn: CachedResolveReferenceLinksComponent: Unknown reference link target 'P:ProjectName.Properties.Resources.TextFile'.

And the Remarks section of the chm changes to:

The help file is loaded from the HelpTextFile().

So my question is a two part one:

1. Is my use of the <see/> element for referencing a resource correct?
2. Is there a way to get sandcastle to reference an embedded resource in the chm files it generates?

Answer 1

You can use an HTML anchor tag to achieve the same result. It's like referencing image files using an <img> tag in the XML comments.

/// The resources are loaded from
/// <a href="../Resources.TextFile.txt">Resources.TextFile.txt</a>.

Include the resource file as a content item in the project. The example above assumes it's in the root folder. HTML files are always in the ./html folder so it needs to go up one level. If you put the file in a subfolder off of the root folder, add its name to the href target: "../FolderName/Resources.TextFile.txt".

If you've applied the Sandcastle Styles patch, you can use an href attribute instead of a cref attribute on the <see> tag. The file location info would be the same.

/// The resources are loaded from
/// <see href="../Resources.TextFile.txt" />.

Eric