How to remove comment delimiter character(s) (ex. leading forward slashes in c#) within the code block component?

Topics: Developer Forum, User Forum
May 1, 2013 at 10:22 PM
Hi.

Thank you for Sandcastle Help File Builder v1.9.1.0.

I have a code block as follows:
<code language="none" source="..\Project1\Class1.cs" region="Region1" />
Class1.cs snippet:
/// <summary>
/// Gets or sets property 1.
/// #region Region1
/// blah
/// #endregion
/// </summary>
/// <value>
/// The property 1.
/// </value>
public string Property1 { get; set; }
In the chm help output, this generates the following:
/// blah
///
However, I would like it to just generate the following:
blah
Is this currently possible and how? Can I replace the default configuration for the code block component (just specifically for this shfbproj)?
Should I create a work item in the Issue Tracker?

The reason I want to do this is to avoid having to maintain the documentation in two different places, but I want to have control of what the generated help topic look like.

Thank you.
Coordinator
May 2, 2013 at 1:49 AM
The code import feature is typically used to import functioning code (i.e. something that you can compile and verify is working). While it can be used to import a chunk of comments, removing the delimiters is not supported. Removal of comment delimiters from imported code isn't something I'd consider adding since that could prove to be rather difficult since the delimiters vary by language and may have varying forms within any given language (i.e. C# has // and /// as well as the potentially multi-line spanning / / and /* /).

If your intent is to import a repeated block of comments, your best bet would be to use a token file and insert a <token> element in the comments. Tokens are supported within XML comments by adding the API Token Resolution component to the project. Since they're replaced with the token content at build time, they would not have any comment delimiters within them.

Eric
May 2, 2013 at 3:58 AM
Edited May 2, 2013 at 4:22 AM
Hi Eric,

Thank you for the quick reply.

Unfortunately, I am not trying to import a repeated block of comments.

I'd like to import parts of XML comments on many properties in a c# class file into a conceptual topic.
I don't want a full API-type of documentation layout, etc.

For example:
Topic1.aml snippet:
    <section address="Property1">
      <title>Property 1</title>
      <content>
        <para>
        <code language="none" source="..\Project1\Class1.cs" region="Region1" />
        </para>
      </content>
    </section>
    
    <section address="Property2">
      <title>Property 2</title>
      <content>
        <para>
        <code language="none" source="..\Project1\Class1.cs" region="Region2" />
        </para>
      </content>
    </section>
Class1.cs snippet:
/// <summary>
/// Gets or sets property 1.
/// #region Region1
/// Must not contain spaces.
/// Required.
/// Default value: DefaultValue1
/// #endregion
/// </summary>
/// <value>
/// The property 1.
/// </value>
public string Property1 { get; set; }

/// <summary>
/// Gets or sets property 2.
/// #region Region2
/// Must not contain commas.
/// Must be less than 10 characters.
/// Default value: DefaultValue2
/// #endregion
/// </summary>
/// <value>
/// The property 2.
/// </value>
public string Property2 { get; set; }
Any other ideas?

Is there an easier way than having to create a new build component for example?

Right now, my only additional requirement is replacing the leading 4 characters on every line.

Thank you very much.
Coordinator
May 2, 2013 at 7:32 PM
I think tokens would still work. If you want them to work between XML comments and MAML topics with specific formatting, you could probably wrap the token content in a <markup> element. The latest SHFB release would be required for that since I only recently added markup element support to the API XSL transformations. That should allow any HTML elements you care to use within it to pass through and format the text however you like. There isn't really any other way to share comments between XML comments and MAML since they use different elements.

Eric
May 2, 2013 at 9:39 PM
Hi Eric,

Thank you for your response.

However, I think there's still a misunderstanding.

I do not want to generate API documentation; I am only interested in generating conceptual document for non-developers.
When using a tokens file, It seems I have to add documentation in that file; I can't just add additional (non-developer) documentation in the source code which is where I want it to be since that's where changes to the application occur, and so changing things in just one place is a lot easier than documentation split across multiple places (tokens, aml, cs) and trying to keep them all synchronized.

Using <token>Example</token> within XML comments works as expected when API documentation is generated; <token>Example</token> is replaced with the content as specified in the tokens file.

Using <token>Example</token> within MAML works as expected; <token>Example</token> is replaced with the content as specified in the tokens file.

However, using it within XML comments as follows:

/// <summary>
/// Gets or sets property 1.
/// #region Region1
/// <token>Example</token>
/// #endregion
/// </summary>
/// <value>
/// The property 1.
/// </value>
public string Property1 { get; set; }

And then using the code block in a conceptual document as follows:

<code language="none" source="..\Project1\Class1.cs" region="Region1" />

The <token>Example</token> will not get replaced in the generated document.

Either way, I want to avoid having to maintain documentation "content" in two different places.

Thank you.
Coordinator
May 3, 2013 at 1:56 AM
The whole point of using the tokens is that you no longer need to import the regions. Get rid of the #region markers surrounding the token in the XML comments and insert a token in place of the <code> elements in the conceptual topics. Both should then resolve to the content of the token at build time based on whatever you are building since you'd be using the same token file in both projects.

You're trying to use imported code blocks in a way that it wasn't designed to support or intended to be used. Tokens are probably the only way you will get the desired result without resorting to creating a build component that imports content rather than code if you don't want to manage the shared content in a token file.

Eric
May 4, 2013 at 12:01 AM
Hi Eric,

Thank you very much for the detailed clarification! :)