The "show missing documentation" build component is used to add "missing" notes for missing namespace comments and summary, parameter, returns, value, and remarks tags. It can also add default summary documentation for constructors. The functionality in this component used to be integrated with the help file builder itself. However, the XPath queries used to look up the information in the comments files and reflection information file proved to be too slow when used on extremely large builds with tens of thousands of topics. By moving the processing to a build component, the amount of information to search is greatly reduced and the time to add missing item comments is now negligible.

Example Configuration

The following is the default configuration for the "show missing documentation" component. It should be inserted into the configuration file before the TransformComponent. All attribute names and values are case-sensitive.

CopyExample Configuration
<!-- Show missing documentation component configuration.  This must
     appear before the TransformComponent. -->
<component type="SandcastleBuilder.Components.ShowMissingComponent"
  assembly="{@SHFBFolder}SandcastleBuilder.Components.dll">
    <!-- All elements are optional. -->

    <!-- Auto-document constructors (true by default) -->
    <AutoDocumentConstructors value="{@AutoDocumentConstructors}" />

    <!-- Auto-document dispose methods (true by default) -->
    <AutoDocumentDisposeMethods value="{@AutoDocumentDisposeMethods}" />

    <!-- Show missing param tags (true by default) -->
    <ShowMissingParams value="{@ShowMissingParams}" />

    <!-- Show missing typeparam tags (true by default) -->
    <ShowMissingTypeParams value="{@ShowMissingTypeParams}" />

    <!-- Show missing remarks tags (false by default) -->
    <ShowMissingRemarks value="{@ShowMissingRemarks}" />

    <!-- Show missing returns tags (true by default) -->
    <ShowMissingReturns value="{@ShowMissingReturns}" />

    <!-- Show missing summary tags (true by default) -->
    <ShowMissingSummaries value="{@ShowMissingSummaries}" />

    <!-- Show missing value tags (false by default) -->
    <ShowMissingValues value="{@ShowMissingValues}" />

    <!-- Show missing namespace comments (true by default) -->
    <ShowMissingNamespaces value="{@ShowMissingNamespaces}" />

    <!-- Show missing include targets (false by default) -->
    <ShowMissingIncludeTargets value="{@ShowMissingIncludeTargets}" />

    <!-- Shared content file containing the localized
         messages (optional) -->
    <contentFile filename="{@WorkingFolder}SharedBuilderContent.xml" />
</component>

The example given above is taken from the Sandcastle Help File Builder's configuration file. When used with it, the replacement tag {@SHFBFolder} is used to insert the help file builder's folder in the file path. This is replaced at build time with the appropriate value. The other elements also use replacement tags that map to the help file builder project options of the same name. If using the component in your own build scripts, replace the tags with actual values. All elements are optional. If not specified, the default value noted in the comment before the element is used.

Localized Messages

If present, contentFile should point to a shared content file that contains the localized auto-documented constructor and "show missing" messages. If omitted, default English language messages are used. The format of the content should be similar to the following (lines wrapped for display purposes):

CopyLocalized Messages Example
<?xml version="1.0" encoding="utf-8"?>
<content xml:space="preserve">
    <!-- SHFB Show Missing Component messages -->
    <item id="shfbAutoDocConstructor">Initializes a new instance
of the &lt;see cref="T:{0}"/&gt; class</item>

    <item id="shfbAutoDocStaticConstructor">Initializes the static
fields of the &lt;see cref="T:{0}"/&gt; class</item>

    <item id="shfbAutoDocDispose">Releases all resources used
by the &lt;see cref="T:{0}"/&gt;</item>

    <item id="shfbAutoDocDisposeBool">Releases the unmanaged
resources used by the &lt;see cref="T:{0}"/&gt; and optionally
releases the managed resources</item>

    <item id="shfbAutoDocDisposeParam">True to release both
managed and unmanaged resources; false to release only unmanaged
resources</item>

    <item id="shfbMissingTag">&lt;p
style="color: #dc143c; font-size: 8.5pt; font-weight: bold;"&gt;[Missing
&amp;lt;{0}&amp;gt; documentation for "{1}"]&lt;/p&gt;</item>

    <item id="shfbMissingParamTag">&lt;p
style="color: #dc143c; font-size: 8.5pt; font-weight: bold;"&gt;[Missing
&amp;lt;{0} name="{1}"/&amp;gt; documentation for
"{2}"]&lt;/p&gt;</item>

    <item id="shfbMissingIncludeTarget">&lt;p
style="color: #dc143c; font-size: 8.5pt; font-weight:bold;"&gt;[Missing
&amp;lt;include&amp;gt; target documentation in '{0}'.  File: '{1}'
Path: '{2}']&lt;/p&gt;</item>

</content>

The Sandcastle Help File Builder's content files contain these entries by default. For information on what each of the "show missing" options does, see Show Missing Tags Category Properties help topic.

See Also