Click or drag to resize
Sandcastle Help File Builder

Documentation Sources

Documentation sources are how you specify the assemblies, XML comments files, and/or solutions and projects that define the reference (API) content of the help file.

Adding a Documentation Source

To add a documentation source, right click on the Documentation Sources project node and select Add Documentation Source... or select File | Project Explorer | Documentation Sources | Add Documentation Source.... An Open File dialog box appears in which you can select one or more DLLs, executables, XML comments files, or Visual Studio solutions/projects associated with the items to document. When adding a DLL or an executable, if an XML comments file with the same name is found, it is also added to the project automatically. Likewise, if you select an XML comments file, a DLL or executable with a matching name is added to the project automatically if it exists. Files can also be dragged and dropped on the node from Windows Explorer.

If a solution file is selected, a dialog box will appear asking whether you want to add the solution as the documentation source or selected projects within it. If the solution file is added, all projects within it will be included when the help file is built including projects added to it at a later date. If you select specific projects from it, only those projects will be added as documentation sources.

Note Note

If you do not add an associated XML comments file for an assembly, no comments will appear on the documented members in the help file topics that are built.

Tip Tip

Given that solutions and projects are supported as documentation sources, you may find it easier to add them as documentation sources instead of the assemblies, comments, and references that they contain. When a solution or project is used, these items are imported from them automatically at build time.

Note Note

Only add assemblies and projects that you want documented to this project node. Third-party assemblies, interop assemblies, and other dependent DLLs should be added to the project's References node.

Editing a Documentation Source

When selected, each documentation source has the following properties that can be edited in the property grid at the bottom of the Project Explorer window. Some of the properties will only apply to certain types of documentation source as indicated.

  • SourceFile - This can be an individual file or it can contain wildcards (* or ?) to include multiple files. If the extension is a wildcard (i.e *.* or ProjectName.*), it will include any assembly, XML comments file, solution or project that matches the wildcard.

  • IncludeSubFolders - If the SourceFile property contains a wildcard, this property will be used to determine whether all matching files are included from subfolders as well (True) or if just the files in the indicated folder are included (False).

  • Configuration - For Visual Studio solution and project documentation sources, this can be used to indicate that a specific configuration value should be used when extracting assembly, comments file, and reference information. If not set, the global Configuration option setting is used. The default global option value is Debug.

  • Platform - For Visual Studio solution and project documentation sources, this can be used to indicate that a specific platform value should be used when extracting assembly, comments file, and reference information. If not set, the global Platform option setting is used. The default global option value is AnyCPU.

  • TargetFramework - For Visual Studio solution and project documentation sources, this can be used to indicate the target framework for projects that use multi-targeting (e.g. net40, netstandard20, net5.0, etc.). This will be used to determine which assembly to use when extracting assembly and comments file information from the projects. If not set, the build engine will make an attempt to determine a common target framework based on all projects given as documentation sources. If one can be found, it will be used. If a common target framework cannot be determined, the first target framework in each project will be used.

Removing a Documentation Source

To remove a documentation source, right click on it and select the Remove option. This can also be selected from the File | Project Explorer | Documentation Sources menu.

See Also