Frequently Asked Questions (FAQ) |
The following are some common problems and solutions along with some known issues with Sandcastle and help files that you may encounter.
Use curly braces in cref targets and HTML entities (< and >) in the general XML comments. For example:
/// <summary> /// See <see cref="IEnumerable{T}"/> for more information. /// <p/>Another reference to IEnumerable<T>. /// </summary>
Embedding an image in an element's help topic is a two step process. First, you must add the image to the help file builder project as a content item (add it using the Project Explorer window and set the BuildAction to Content). The second step is to edit the member's XML comments (summary, remarks, etc) to add the img tag. To embed an image in the project summary or namespace comments, add the image tag to the help file builder's ProjectSummary property text or to a namespace's comments using the NamespaceSummaries project property.
Below are two examples of embedding an image in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the image file. The first example assumes that the image is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the image is copied to an .\Images folder. In that case, you must also specify the folder name. As noted above, the image tag must be self-closing to conform to the XML specification.
/// <summary> /// A class member. /// </summary> /// <remarks>An image: <img src="../Process.gif"/> /// </remarks> public void TestMethod() { // ... Method implementation ... } /// <summary> /// A useful class. /// <p/>UML Diagram: <img src="../Images/TestClassUML.gif" /// alt="UML Diagram" /> /// </summary> public TestClass { // ... Class implementation ... }
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.
Sandcastle was designed to document code based on a set of XML comments and API information found in a reflection information file. As such, it requires at least one assembly in order to produce a help file containing API documentation. If you do not include at least one assembly with a namespace containing at least one public class, the help file cannot be produced. To produce help files unrelated to assemblies, you can use some other tool such as the HTML Help Workshop or one of the commercial equivalents.
You can use the Additional Content Only plug-in to produce a help file based on conceptual content and/or additional content items alone. To do so, add the plug-in to the project via the PlugInConfigurations project option, add conceptual and/or additional content to the project, and build the help file. See the Additional Content Only Plug-In help topic for more information about it. See the Conceptual and Additional Content topic for more information about how to utilize conceptual and additional content files.
In order to document Compact Framework applications you also need to add a reference item for the Compact Framework assemblies. These are usually located under the Visual Studio 2005 installation folder. The easiest way to reference them is to add the Wildcard References Plug-In to the project's PlugInConfigurations property and add an entry to its configuration for a path similar to the following:
%VS80COMNTOOLS%\..\..\SmartDevices\SDK\CompactFramework\2.0\v2.0\WindowsCE\
This will expand the VS80COMNTOOLS environment variable in order to find the Visual Studio 2005 installation location and append the necessary path to find the Compact Framework assemblies. See the References topic for more information on adding reference items.
If the SDK link type project property related to the help file format you are building is set to MSDN, BuildAssembler will attempt to contact the MSDN web service to resolve links to SDK topics. If you are behind a proxy server, this will most likely fail and will abort the build process with an error similar to "HTTP status 407: Proxy Authentication Required" or "HTTP status 417: Expectation Failed". The simplest fix is to set the HtmlSdkLinkType and WebsiteSdkLinkType properties to None, the MsHelp2SdkLinkType property to Index, and the MSHelpViewerSdkLinkType property to Id. The downside for the HTML Help 1 and website formats is that you will not get links to online SDK content. For the MS Help 2 and MS Help Viewer formats, the noted value generates links to the local help content when merged with the collection.
It has been reported that creating a BuildAssembler.exe.config file in the same folder as BuildAssembler.exe (the root help file builder installation folder) and putting one of the following in it may allow it to work with the proxy server:
<configuration> <system.net> <defaultProxy useDefaultCredentials="true"> <proxy usesystemdefault="true"/> </defaultProxy> <!-- Add this setting if you get an HTTP 417 error. --> <settings> <servicePointManager expect100Continue="false" /> </settings> </system.net> </configuration>
<configuration> <system.net> <defaultProxy enabled="true" useDefaultCredentials="true"> <proxy bypassonlocal="true" proxyaddress="http://yourproxy:8080" /> </defaultProxy> <!-- Add this setting if you get an HTTP 417 error. --> <settings> <servicePointManager expect100Continue="false" /> </settings> </system.net> </configuration>
<configuration> <system.net> <defaultProxy useDefaultCredentials="true"> <proxy scriptLocation="http://your.server.com/proxy.pac" usesystemdefault="true" /> </defaultProxy> <!-- Add this setting if you get an HTTP 417 error. --> <settings> <servicePointManager expect100Continue="false" /> </settings> </system.net> </configuration>
This error affects a small number of people and is caused by one of the help components (ITCC.DLL) either not getting installed or not getting registered correctly. Search your system for the DLL. If not found, you can either locate it on another system that has the Help 2 components or you can search Google for it. Once you obtain it, you will need to copy it to the failing system and register it. This can be done by running the following command from a command prompt. Adjust the path to the DLL as necessary based on its location on your system.
regsvr32 C:\Windows\System\itcc.dll
For an MS Help 2 file (.HxS), you need a separate viewer to load the help file or you need to integrate it into an existing collection. See the Links to Resources topic for a link to a freeware Help 2 viewer and a tool that can help you register your help file with a collection.
For HTML Help 1 files (.CHM), if the path to the help file contains "#", the help file may fail to load. The apparent reason for this is that the help viewer considers the "#" to be an unsafe character and it must be encoded for it to use it. Rename the folder to remove the "#" to get the file to load.
Another cause for the pages not displaying is a security patch that prevents the help viewer from running from the intranet zone (i.e. a network share). You can fix this problem by saving the following to a file and importing it into the registry.
Windows Registry Editor Version 5.00 [HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft\HTMLHelp\1.x\ItssRestrictions] "MaxAllowedZone"=dword:00000001
It may also be possible to unblock the file so that it can be viewed by right-clicking on it, selecting Properties and clicking the Unblock button on the General tab if it is there.
The most likely cause of an empty help file or one that does not contain all of your assembly's classes is that the missing classes are not declared public. By default, when you add a class to a Visual Studio project, it does not add the public keyword to it. As such, you must remember to edit the class to make it public if necessary. Sandcastle does not document private and internal methods by default either. If you really want to see them in the help file, set the DocumentPrivates and/or DocumentInternals project properties to true.
You should also check the project to be sure that it does not have an ApiFilter defined that is excluding the items in question. An <exclude /> tag in the item's XML comments will also cause it to be removed from the documentation.
Another possible cause of missing classes is compiling a help file project using the wrong framework version selection. For example, if you compile a .NET 2.0 help project with the FrameworkVersion project property set to a .NET 1.x version number, you may end up with lots of missing classes. As such, check the property to be sure that it is set appropriately.
You either have not enabled the Visual Studio project option to produce an XML comments file for your assembly, it has a name different from that of the assembly and the help file builder did not see it when you added the assembly to the project, or the XML comments filename is not unique. Check the Documentation Sources node in the Project Explorer window. You should see the assembly name and the XML comments filename listed. If you added a solution or project file as a documentation source, check the build log to see if it found the correct assembly and XML comments file. See the Walkthrough: Enabling and Using XML Comments topic for information on enabling the XML comments file option in Visual Studio.
Be sure to give each project's XML comments file a unique name as they are copied to a common location for the build. Identically named files may overwrite each other and the documentation in the overwritten files will not appear in the help file. If the comments file options are set correctly, check to be sure that the XML comments in your source files are preceded by a triple slash for C# code (///) or a triple quote for VB.NET (''').
The help file builder automatically includes a copy of the Code Block Component that adds several attributes to the <code> tag. One of these is the lang attribute that lets you specify the language rules to use when colorizing the code. It is also used to indicate the code filter to which the sample should be connected. If omitted, the component will assume that the code is C#. You can change this behavior by adding a lang attribute that specifies a different language. You can also specify "none" as a value to disable colorization and the code filter for it.
If the majority of your code samples are in a language other than C#, you can override the default by using the ComponentConfigurations project property to add the Code Block Component to the project and configure it to use a different default setting.
For non-English HTML Help 1 help files, the help title will not appear on the title of the help window unless the system's language matches the help file's language exactly. This is a known issue with the way the help viewer compares the language values.
To resolve encoding issues, add the DBCS Fix for CHM Builds Plug-In to the project. See the plug-in documentation for information about its configuration.
The HTML Help 1 compiler does not appear to support Unicode encoding of its project and table of contents files. This may cause the help title to display incorrectly if it contains extended characters that need encoding.
To resolve encoding issues, add the DBCS Fix for CHM Builds Plug-In to the project. See the plug-in documentation for information about its configuration.
Edit the member's XML comments (summary, remarks, etc) to add an anchor (<a>) tag that points to the additional content page. To add a link in the Project Summary or Namespace comments, add the anchor tag to the help file builder's Project Summary notes or namespace comments. Below are two examples of adding a link in the XML comments. Note that all namespace help topics reside in an .\html folder so you must use a relative path to go up one level to find the additional content file. The first example assumes that the file is copied to the root of the help project. As such, no additional path beyond the relative indicator is required. The second example assumes that the file is copied to a .\Tutorials folder. In that case, you must also specify the folder name.
/// <summary> /// A class member. /// </summary> /// <remarks>Class usage tutorial: /// <a href="../SomeClassTutorial.html">SomeClass Tutorial</a> /// </remarks> public void TestMethod() { // ... Method implementation ... } /// <summary> /// A useful class. For more information see the /// <a href="../Tutorials/SomeClass.html">tutorial</a>. /// </summary> public TestClass { // ... Class implementation ... }
For information on writing your own custom build components, see the Creating a BuildAssembler Build Component topic.
Set the project's NamingMethod property based on your preference and see the NamingMethod help topic for examples that show how to open specific topics based on the selected naming method from application code and how to determine the URL for a website link.