NDoc User's Guide NDoc 1.3

What's new in NDoc 1.3 ?

[This is preliminary documentation and subject to change]

What's new in NDoc 1.3 ?

NDoc 1.3 incorporates a very large number of new and enhanced features as well as bug fixes.

Highlights

NDoc 1.3 includes many new features:

"VS.NET 2003" Documenter

The new "VS.NET 2003" Documenter creates HTML Help 2 documentation, with fully populated XML data islands, resulting in much better integration with the Visual Studio help system.

The new documenter produces documentation that more closely matches the latest MS documentation and includes features such as language filtering of syntax and outher text sections.

More information on this documenter can be found here

Performance

The performance of all documenters has been significantly improved.

Assembly Loading

A number of improvements have been made to Assembly loading.

Internationalization

NDoc can now process assemblies and comments with non-english characters.

Full Unicode (RTF-8) support is available in all documenters except MSDN HtmlHelp. There are some known problems with support for mixed character-sets in the HTML Help compiler, however these are out of our control...

Note that while we support other character-sets, NDoc generated text such as section headings cannot be localized in this release.

Concurrent NDoc runs

Multiple instances of NDoc can now be run concurrently. Previous problems with file locking have been resolved.

User Interface

XML Documentation Tags

New Tags
Tag Comments
<exclude/> Directs NDoc to exclude the tagged type or member from the documentation.
The tag overrides all visibility options.
<preliminary> Marks the documentation of a type or member as preliminary.
This tag can include text and block tags like <para> in order to put a custom warning into your help topics about preliminary items.
If the tag is empty, preliminary topics will include the default message:
[This is preliminary documentation and subject to change.]
It is also possible to mark an entire help project as preliminary using the Preliminary project setting.
<devdoc>  
Enhanced Tags
Tag Comments
<code>
  • "lang" attribute
  • No more <include> to prevent indent
  • "Escaped" attribute
<see> langword

Settings

New Settings

The following settings have been added to all documenters.

Setting Comments
Main Settings
CleanIntermediates If true, intermediate files will be deleted after a successful build.
For documenters that result in a compiled output, like the MSDN and VS.NET documenters, intermediate files include all of the HTML Help project files, as well as the generated HTML files.
FeedbackEmailAddress If an email address is supplied, a mailto link will be placed at the bottom of each page using this address.
Preliminary If true, NDoc will mark every topic as being preliminary documentation.
The default notice is [This is preliminary documentation and subject to change.]
SdkDocVersion Specifies to which version of the .NET Framework SDK documentation the links to system types will be pointing.
SdkDocLanguage Specifies to which Language of the .NET Framework SDK documentation the links to system types will be pointing.
Show Attributes
DocumentInheritedAttributes If true, NDoc will document, in the syntax portion of topics, the attributes inherited from base types/members.
Visibility
DocumentedInheritedMembers Determines what types of inherited members are documented.
DocumentInheritedFrameworkMembers If true, members inherited from .Net framework classes will be documented.
DocumentExplicitInterfaceImplementations If true, members which explicitly implement interfaces will be included in the documentation.
Normally, these members will not documented.
DocumentSealedProtected If false, protected members of sealed classes will not be documented.
Normally, these members will not documented.
SkipNamespacesWithoutSummaries If true, NDoc will not document namespaces (nor any types within them) if an associated namespace summary does not exist.
Retired Settings

The following settings have been 'retired'.

Setting Comments
Main Settings
GetExternalSumeries The performance of the Xml merge process has been considerably improved, and so summary information for inherited members is now always included (when available).
IncludeNamespaceHierarchy Performance and stability problems with Namespace hierarchies have been resolved, and so namespace hierarchy pages are now always generated.

MSDN Documenter

New Settings

The following settings have been added.

Setting Comments
Main Settings
BinaryToc If true, the documenter will produce a binary TOC. This can considerably improve the performance on opening a chm with a large table-of-contents.
Normally this is set to true, but be aware that there are a few limitations imposed if using binary TOCs; see the Html Help Workshop help for more details...
Title The documentation title shown in the banner at the top of every topic.
Extensibility
ExtensibilityStylesheet see here for further details.
HTML Help Options
AdditionalContentResourceDirectory Directory that contains resources (images etc.) used by the additional content pages. This directory will be recursively compiled into the help file.
LangID The language ID of the locale used by the compiled helpfile
Retired Settings

The following settings have been 'retired'.

Setting Comments
Main Settings
SortTOCByNamespace The Table-of-contents always shows Namespaces in sorted order.
SplitTOCs This setting was used to overcome limitations in the old HtmlHelp2 documenter.
With the introduction of the VS.NET documenter, this setting is no longer required.
DefaultTOC The first namespace is now always the default selected item in the Table-of-contents.
LinkToSdkDocVersion This setting has been superseded by SdkDocVersion and SdkDocLanguage, which are common to all documenters.
NDoc will still read this setting, but the GUI will convert to the new settings on save of a project.
Improved hypertext linking logic

When a <see> reference to an item appears more than one time within a section on a page, only the first occurrence is linked, the following are just highlighted in bold.  This reduces the visual 'clutter' on a page.

Table-of-Contents Page Icons

The icons used in the Table-of-Contents for documentation pages are now 'blank' rather than containing a question mark (?).

Operators and Type Conversions

Operators and Type Conversions are now correctly handled in the Table-of-Contents, and the page formatting more closely matches MSDN.

Attribute Handling

ObsoleteAttribute

The MSDN and VS.NET documenters will automatically add text to indicate that a type has the ObsoleteAttribute.

FlagsAttribute

If a type has FlagsAttribute applied, the MSDN and VS.NET documenters will automatically add the following text to the end of the summary on the type overview topic.

"This enumeration has a FlagsAttribute attribute that allows a bitwise combination of its member values."