Click or drag to resize
Sandcastle Help File BuilderSharing Project Summary and Namespace Comments

If you are documenting multiple, related assemblies but wish to use a separate help file builder project for each assembly, you may want to share project summary and namespace comments between each of the projects and specify a common set of namespaces to exclude from the build. Rather than managing this information in each individual project, you can create a standalone XML comments file to contain the information.

Start by creating an XML comments file like the following and give it a unique name that will not conflict with any other XML comments file in the related projects.

Sample Project/Namespace XML Comments File
Copy
<?xml version="1.0"?>
<doc>
  <assembly>
    <name>_SharedItems_</name>
  </assembly>
  <members>
    <member name="R:Project_CustomControlsHelp">
      <summary>
        Shared project summary comments go in here.
      </summary>
    </member>
    <member name="N:">
      <exclude />
      <summary>
        Exclude the global namespace from all projects.
      </summary>
    </member>
    <member name="N:CustomControls.Internal">
      <exclude />
    </member>
    <member name="N:CustomControls.Design">
      <summary>
        Common namespace summary info for the CustomControls.Design
        namespace go here.
      </summary>
    </member>
  </members>
</doc>
Important note Important

The project summary comments will be placed in the member with the ID starting with "R:Project_". The ID must be suffixed with the value from your project's Html Help Name property. Replace any spaces in the value with underscores. This is required so that the root namespace container has a unique name that will not cause any conflicts when building MS Help Viewer output.

Next, do one or more of the following:

  • To specify shared project summary comments, add them to the <summary> tag in the R:Project_[HtmlHelpName] node. As noted above, substitute the value of your project's Html Help Name property in the ID. Any project summary comments in the help file projects will be appended to these comments. If you do not have any shared project summary notes, you may remove this node from the file.

  • To exclude a namespace from all shared projects, add a <member> node, set it's name attribute to the namespace name prefixed with "N:", and place an <exclude /> tag in it. Any other tags are optional. The example above would exclude the unnamed global namespace and the CustomControls.Internal namespace from all projects.

  • To specify shared namespace summary comments, add a <member> node, set it's name attribute to the namespace name prefixed with "N:", and add the comments to the <summary> tag in the node. Any namespace summary comments in the help file projects will be appended to these comments.

  • To specify shared namespace group summary comments, add a <member> node, set it's name attribute to the namespace group name prefixed with "G:", and add the comments to the <summary> tag in the node. Any namespace group summary comments in the help file projects will be appended to these comments.

Once you have created the file, open each project that needs to use it, right click on the Documentation Sources node in the Project Explorer window, select the option to add a documentation source, and select the shared comments file. You may now build your project and the shared comments will be included in it.

See Also