Summaries Category Properties

The Summaries category properties allow you to specify project summary and namespace summary comments.

The Project Summary property allows you to enter summary comments that should appear in the root namespaces page of the compiled help file. This is the standard default page unless additional or conceptual content is defined that is marked as the default page. Depending on the presentation style, the Namespaces page is also accessible via the breadcrumb link available at the top of the namespace item help pages in the generated help file. These comments will appear above the list of namespaces and can contain HTML markup (i.e. text formatting, e-mail links, etc.). The comments can also include the <inheritdoc /> tag so that you can import the description or parts of a description from another namespace, type, or member. If no project summary is defined, the page just shows the list of namespaces.

Clicking the Edit Namespace Summaries button allows you to specify which namespaces should appear in the help file as well as the namespace summaries to display in the root namespaces page and on the help page for each namespace.

When the form is opened, it scans the documentation assemblies for new namespaces and adds them to the list if it finds any. If namespace grouping is enabled in the project, entries are added for each namespace group as well. As you select each namespace, the list of assemblies in which it appears is shown to the right and its current description appears in the text box below the lists. Namespaces can be filtered by assembly and/or by entering some text or a regular expression to match and clicking the Apply button. Setting the assembly combo box back to "<All>", clearing the search text, and clicking Apply will redisplay all assemblies.

To edit a namespace summary, select the namespace in the list and edit the comments in the text box at the bottom of the form. The comments can include HTML markup (i.e. bolding, e-mail links, etc). If no summary is defined, a red warning note will appear for the namespace on the root namespaces page and above the namespace content in the help page for the namespace itself. If you build a help file without updating the namespace list, any unknown namespaces will appear in the help file but they will also contain a red warning message indicating that the namespace summary is missing. The warning can be removed by setting the Show Missing Namespaces project option to false. Namespace summaries also support the <inheritdoc /> tag so that you can import the description or parts of a description from another namespace, type, or member.

Namespaces are never removed from the list even if the namespace no longer appears in one of the documented assemblies. You can remove old namespaces from the list by selecting them and clicking the Delete button. The "(global)" namespace is a special case and, although it can be deleted, it will be added automatically to remove unwanted information that appears in the global namespace.

You may check the namespaces that you want to appear and uncheck those that you do not want to appear. By default, all namespaces in all assemblies are documented with the exception of the global (unnamed) namespace that sometimes appears and contains private module details. This information is automatically merged with the project's Api Filter settings at build time. To avoid conflicts, you may want to leave all of your namespaces checked here and use the API Filter Property exclusively to manage the namespaces excluded from the documentation.

Other Resources