What is the correct way to reference Embedded Resources in the .net xmldoc comments?
I have a C # project that uses xml comments . I am making chm files of these from Sandcastle via Sandcastle File Builder Help . One of the member functions in this project uses an embedded resource . I want to reference it in the help file. Sandcastle doesn't seem to support this, but the xml documentation files it parses do. 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 this code and compile 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:
The help file is loaded from the [!:Resources.TextFile.txt].
If I do as Agent Smith for ReSharper suggests and changes the <see> item in the <see cref="Resources.TextFile"/>
build log says:
Warn: CachedResolveReferenceLinksComponent: Unknown reference link target 'P:ProjectName.Properties.Resources.TextFile'.
And the Remarks section in chm changes to:
The help file is loaded from the HelpTextFile().
So my question has two parts:
- Am I using the <see /> element to reference the resource correctly?
- Is there a way to get sandcastle to reference the embedded resource in chm generated files?
source to share
You can use HTML anchor tag to achieve the same result. This is similar to linking to image files using the <img> tag in 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 this is in the root folder. HTML files are always in the folder. / html, so you need to go up one level. If you place the file in a subfolder from 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 the href attribute instead of the cref attribute on the <see> tag. The file location information will be the same.
/// The resources are loaded from
/// <see href="../Resources.TextFile.txt" />.
Eric
source to share