Using tokens in code comments?

Topics: User Forum
Sep 27, 2010 at 7:35 PM
Edited Sep 27, 2010 at 10:33 PM

Is there an easy way to use something like tokens in code comments? For example, if I wanted to document my Main method as "/// <summary>The main entrypoint for <myProject/></summary>" and then have the "<myProject/>" part replaced with the actual name of my project so that it's consistent and making an easy transition from a code-name to the final production name?

I could manually run XslTransform.exe with a custom XSL on the C# generated XML files and copy them to the working directory, but I was wondering if there is a simpler solution that I'm probably missing.

Just to clarify, I wasn't necessarily looking to modify main_sandcastle.xsl, but rather easy snippets to save repetitious typing, like tokens in conceptual content. 

The end goal is to have less things to edit/merge when a new drop of Sandcastle and/or Sandcastle Styles is updated. Another option might be to pass an argument to the main_sandcastle.xsl transform that would be the path to my custom style sheet, then the only change needed to main_sandcastle.xsl would be to include that href path. Is that possible?

Thanks in advance!

Sep 28, 2010 at 8:32 PM

By default, tokens are only supported in conceptual topics.  Token replacement there is handled by the SharedContentComponent.  I just did a quick test and it can be used in the API build.  Here's how:

1. Create a component configuration file to contain a definition that SHFB can import into your project via the ComponentConfigurations project property.  Call it something like APITokenResolution.components and place it in the "%ProgramData%\EWSoftware\Sandcastle Help File Builder\Components and Plug-Ins" folder.  Substitute %ALLUSERSPROFILE% if on XP or Vista.  You will need to create the folder first if you don't have any other custom component definition files.  The content of the configuration file is as follows:

<?xml version="1.0" encoding="utf-8"?>

<!-- CustomComponent.components example -->
  <component id="API Token Resolution"
      <description>This build component is used to resolve tokens in XML
comments files.</description>

      <insert placement="before"
        id="Show Missing Documentation Component" />

          <!-- Put the path to your token file here -->
          <content file="..\..\Tokens.tokens" />
          <replace elements="/*//token" item="string(.)" />


2. Add a new Token File to the SHFB project and add the tokens you want to it.

3. Edit the ComponentConfigurations project property.  You should see the "API Token Resolution" component listed.  If not, close and re-open SHFB so that it rescans the custom components folder for the file.  Add it to the project and edit its configuration.  Set the path in the "content" element to the path to your tokens file.  I set the default configuration to look in the project folder assuming you are using the default working path and a token file called Tokens.tokens.  Adjust the path and filename as needed.

4. In your XML comments, use a <token> element to specify the replacement token name.  For example:

/// <summary>
/// My project name is <token>ProjectName</token>
/// </summary>

5. Build your VS project to update the XML comments files and then build the help file and you should see the replaced token value in the help topic.

Note that the path is specified explicitly in the configuration as SHFB will not copy token files if there is no conceptual content.  If your project does have conceptual content, you can replace the <content> line with a line containing the text {@TokenFiles} and SHFB will insert the list of token files found in the project for you.  If you need some help getting this working, let me know.



Sep 28, 2010 at 8:55 PM
Edited Sep 28, 2010 at 8:56 PM

Thanks Eric!

I like the approach you suggested for re-using tokens as-is. 

I was also curious if I could use a short-hand of "<myProject/>" in my XML comments, so I went ahead and created a "Custom Tags" plugin that inserts itself before BuildStep.TransformReflectionInfo. It applies a CustomTags.xsl that resides in the project's directory (if it exists) using a XslCompiledTransform to each of the BuildProcess.CommentFiles.Comments (e.g. it applies the transform to the .Comments XmlDocument and then re-.Load's the result. Thus, my CustomTags.xsl has a:

<xsl:template match="myProject" >My Project Name</xsl:template>

in it which is similar to a token. This also gives me the option to use other XSL techniques.

There's probably a better way of doing the above, but it seems to be working.

Thanks again for your response,


Sep 23, 2011 at 2:29 PM

Can the same method be used in the content layout file? I have a token file containing the current release version of our software and would like it to be used in the conceptual content (working fine) and in the content layout title. Currently the Title or TocTitle show the untranslated text e.g. "Welcome to <token>PRODUCT_NAME</token>".



Sep 25, 2011 at 12:15 AM

Token replacement is only for the topic body and is handled by the Sandcastle XSL transformations.  It isn't supported in the property items in the content layout file.