Documenting Assemblies

This topic covers common questions and issues related to documenting assemblies.

• How do I add a logo to the header in my help file topics?
• When I build my project, the BuildAssembler step generates a lot of warnings from ResolveReferenceLinkComponent stating "Unknown reference link target: XXXX". How do I suppress these?
• My project relies on third-party assemblies and/or interop assemblies that do not have XML comments files. How can I document my assemblies without them?
• My project uses third party assemblies but I don't want to include them in my documentation. How do I exclude them?
• How can I create an IntelliSense XML comments file that contains information on only the members documented in the help file and excludes all of the private member details?
• How can I share project summary and namespace settings between multiple help file builder projects?
• I have an assembly without code and without an XML comments file for which I'd like to create documentation and/or an Intellisense file. How can I do that?

To add a logo to the topic headers, do the following:

• In the Solution Explorer tool window (Project Explorer in the standalone GUI), right click on the help file builder project node and select the option to add a new folder to the root of the project. Name the folder "icons". The name must be in lowercase.

• Right click on the new icons\ folder and select the option to add a new image file or select the option to add an existing file and select the image you want to use.

• Right click on the image file that you added to the project and select the Properties option to view the file properties. In the file properties tool window, change the Build Action property to "Content". This ensures that the logo file is included in the help content and it will be placed in the icons\ folder in the help content.

• Right click on the project node again and select Properties to open the help file builder project properties. Select the Transform Args category.

• Locate the logoFile transform argument property in the list. If one does not appear, your selected presentation style or the help file format does not support it. If it does and the property appears, enter the filename as the property value. Enter the filename alone omitting all path information (i.e. HelpLogo.jpg rather than icons\HelpLogo.jpg).

• If building website output and your web server is case-sensitive, be sure to match the case of the folder name in your project with that of the presentation style. The same applies to the logo filename itself.

• Set the other logo transform arguments such as the placement, alignment, and dimensions as needed.

After performing the steps above, you should see the logo in the topics after rebuilding your help file.

If third-party assemblies are referenced by your documented types, you may see warnings about unresolved reference links. All this means is that the topic tried to generate a link to the indicated member but could find no information for it to generate a valid link. In such cases, the member name will be rendered in bold text rather than a clickable link that takes you to its topic.

These warnings can be safely ignored. If you find them bothersome, you can add the Additional Reference Links Plug-In to your help file builder project. This plug-in will generate the necessary information to suppress the warnings or generate links to the members if the selected help file format supports it (i.e. MS Help Viewer). See the plug-in topic for more information.

Third-party assemblies with or without XML comments files and Visual Studio generated interop assemblies do not need to be documented. They are considered to be dependent or reference assemblies. As such, add them to the References node in the Project Explorer window rather than as documentation sources. See the References topic for more information.

See the answer to the previous question.

Add the IntelliSense Component to the project using the ComponentConfigurations project property.

Create a standalone XML comments file and add it to the project as a documentation source. See the Sharing Project Summary and Namespace Comments help topic for details.

Create a blank XML comments file like the following and name it after the assembly with a .xml extension:

<?xml version="1.0"?>
<doc>
  <assembly>
    <name>YourAssemblyNameHere</name>
  </assembly>
  <members>
  </members>
</doc>

Create a new help file builder project and add just that assembly and comments file to it as documentation sources. Select the ComponentConfigurations property and click the "..." button to the right of it. In the Component Configurations dialog, add the IntelliSense Component to the project. Next, set the project's Show Missing Tags properties to your liking. This will force the build to add "missing" notes for all items that you might want to document. Build the project and you will find a new XML comments file named after the assembly in the project's output folder. Edit the <member> elements in the XML comments file to add the comments that you want for each member. For example:

<member name="M:SandcastleBuilder.Utils.XmlCommentsFileCollection.FindMember(System.String)">
  <summary>
  Search all comments files for the specified member.  If not found, add the
  blank member to the first file.
  </summary>
  <param name="memberName">The member name for which to search.</param>
  <returns>The XML node of the found or added member</returns>
</member>

When you are done, replace your original placeholder file with the one generated from the build with your edited comments.

Other Resources