How to merge member documentation from two sources?

Topics: User Forum
Mar 14, 2013 at 6:00 PM
Hi. I am using Visual Studio 2010 integration of SHFB 1.9.6.0 to build a VS2005-style intranet website from several DLLs and XML documentation files. This works great. Now, I'd like to insert extra "see also" links into the web pages of some classes and properties, but I don't want to change the original XML documentation files.

I created a new XML documentation file "clr-link-0.xml" in which the <member> elements have the same name attributes as in the original file, but instead of <summary> and <remarks> elements, clr-link-0.xml only has the <seealso> elements that I want inserted. I then added clr-link-0.xml as a documentation source and built the project, expecting Sandcastle to merge the documentation from the two sources. Unfortunately, the "see also" links did not appear in the generated HTML. In the Help\Working\sandcastle.config file, the "Copy in comments" step lists all the XML documentation files under the same <index name="comments" value="/doc/members/member" key="@name" cache="100"> element, and clr-link-0.xml precedes the original XML documentation files, presumably due to alphabetical order. I think what happened is that CopyFromIndexComponent found the same @name string in two XML documentation files and used only the last one, and it did not warn about this because each file apparently has duplicateWarning="false".

I suspect that, if I changed the sandcastle.config file to define a separate index just for the clr-link-0.xml file and run another copy action from that index, then I might get the member documentation merged. However, I don't quite understand how to make such a change from within the SHFB project. Should I define a build process plug-in or a custom build component?

If it is not possible to make Sandcastle merge the documentation, then I suppose I can do the merging with a separate program and add only the results of the merge as documentation sources. I'd like to avoid that, though.
Coordinator
Mar 14, 2013 at 9:06 PM
The behavior you are seeing is expected. In the case of duplicates, the last seen entry wins. You could create a plug-in to merge the comments although if there are no overlaps such that you don't have to merge the content of like-named elements (i.e. merging summaries or remarks), you could probably just create a custom build component definition that mimics the existing instance and copies in the extra information.

I haven't tested this so if it doesn't work, let me know.

Create a component configuration file like the following.
<?xml version="1.0" encoding="utf-8"?>
<components>
  <component id="Additional Comments Component" type="Microsoft.Ddue.Tools.CopyFromIndexComponent"
    assembly="{@SandcastlePath}ProductionTools\BuildComponents.dll">
    <description>Copy in additional comments from user-defined files.</description>

    <insert placement="after" instance="3" type="Microsoft.Ddue.Tools.CopyFromIndexComponent" />

    <!-- Use the default XML configuration editor -->
    <configureMethod name="" />

    <defaultConfiguration>
      <index name="extraComments" value="/doc/members/member" key="@name" cache="30">
        <!-- Add your files here -->
        <data files="{@ProjectFolder}\clr-link-0.xml" />
      </index>
      <copy name="extraComments" source="*" target="/document/comments" />
    </defaultConfiguration>
  </component>
</components>
Place that file in the Components and Plug-Ins shared folder (see the special folders topic for the location).

Restart SHFB and you should be able to add the component to your project and configure it. Edit the configuration to include the file references you need. The "{@ProjectFolder}" tag will be expanded to the project folder at build time. Add your extra comments files to the root folder of the project rather than as documentation sources since they aren't being included in the usual manner.

When you build, it should load the extra comments and merge them in.

Eric
Mar 15, 2013 at 5:43 PM
Thank you. I will try your suggestion and report back.
Mar 22, 2013 at 11:36 PM
Your "Additional Comments Component" indeed does what I asked for; thank you!

It seems that, if an SHFB project uses this kind of custom component, then the .components file has to be installed to every computer where the project is built, because the <insert placement="after" instance="3" type="Microsoft.Ddue.Tools.CopyFromIndexComponent" /> element does not get copied into the .shfbproj file. Is this correct? It would be more convenient for future maintainers of the project if they could just check out the project from version control and build the working copy, without having to install the custom component first. Can the *.components file be kept in the project directory somehow?

Now that I have the additional "See also" links in the output, I'm hungry for more: a whole new collapsible section, somewhere near Dependency Property Information. Can that kind of thing be added with a build component, or would it require a new presentation style? If I understand correctly, xsl:template[@name="body"] in Sandcastle\Presentation\vs2005\transforms\main_reference.xsl generates the list of sections and does not provide any extension points for such a purpose. However, I might be able to embed the new section into Remarks and then run a separate transformation to pull it out. Perhaps that wouldn't be any easier than writing a new presentation style, though.
Coordinator
Mar 24, 2013 at 2:14 AM
Component information is determined by looking in a common set of well known locations. The information is loaded once and there are no provisions for project-specific component or plug-in definition files since the information is common to all projects. Keeping track of which ones are project-specific and loading and unloading the info with each project is extra overhead for something I don't see being used very often. The custom configuration file could be checked in with the project with either notes in the file or a Read Me file describing how to install it for use. It only has to be done once and then it is available all the time to any project.

Regarding the new collapsible section, that's probably best done by extending the XSL transformations for the presentation style. You can clone a presentation style and give it a new name to isolate your changes so that you don't lose them when a new release of the Sandcastle Tools comes out. See the Custom Presentation Style Definition File topic and its walkthrough for more information.

Eric