What's new in NDoc3 1.0 ?
NDoc3 Beta 4 incorporates new features related to better .NET 2.0, 3.0 and 3.5 support.
Highlights
- Support for generics
- Support for generic constraints
- Support for asymmetric property accessors
NDoc3 are build upon the NDoc project which has been dead for some time. Below are listed the most recent changes for the NDoc project.
Please be adviced that some of the features in NDoc have been temporarily disabled in NDoc3, fx. the "VS.NET 2003" Documenter.
What's new in NDoc 2.0 ?
NDoc 2.0 incorporates a very large number of new and enhanced features as well as bug fixes.
Highlights
NDoc 2.0 includes many new features:
- A complete re-implementation of the Html Help 2 documenter, now known as the "VS.NET 2003" documenter.
- Support for new code commenting tags like preliminary, threadsafety and exclude.
- Support for the ObsoleteAttribute and FlagsAttribute attributes.
- An extensibility feature that allows you to define your own code comment tags and control their formatting.
- User interface enhancements.
- Major performance enhancements in both reflection and document production.
- Better consistency between NDoc generated topics and MSDN topics.
"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.
- The XML Merge process has been speeded-up considerably, and is now only a small percentage of the total processing time regardless of the size of an NDoc project.
- Page production time has decreased by 20-50%.
- Memory usage has been significantly reduced.
- Namespace Hierarchies are produced without performance or stability problems, and are now always documented.
Assembly Loading
A number of improvements have been made to Assembly loading.
- The GUI no longer has to be restarted to reflect changes in an assembly.
- Most assemblies may now be loaded from network shares. However, due to .NET framework limitations, managed C++ assemblies must reside on a local drive or else security exceptions will be raised.
- Assembly resolution has been improved, it is now far less likely that an assembly will fail to be found.
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
- Drag and Drop. Assemblies may be added to a project by drag and drop from explorer to the assemblies list in the NDoc GUI.
- Error Handling. Error Handling has been considerably improved.
- Help Compiler Messages. Help compiler messages are now written to the log, and error messages are shown if an error occurs during compilation.
- Property Grid. The property grid has been enhanced in several respects.
- Assembly Loading Errors.
- Assemblies without XML docs can be documented
- Relative Assembly Paths
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> |
|
| <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.
- On Namespace and Type Member list tables the summary will be start Obsolete.
- On Type Overview and Member Topics, the following text will be added
before the summary description,
NOTE: This member_type is now obsolete.
If the ObsoleteAttribute description property is set, the description text will be displayed on the following line.
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."