NDoc User's Guide NDoc 1.3

NDoc Documenter Basic Settings

[This is preliminary documentation and subject to change]

Overview

A Documenter represents a particular method of creating, organizing, formatting and packaging your documentation. NDoc ships with six Documenters:

NDoc uses a pluggable architecture, so it is also possible to generate your own, custom, documenters.

Generating the documentation consists of two basic steps:

  1. Merging the /doc XML summary with reflected meta-data from the assemblies.
  2. Transforming that merged XML into the documentation (HTML for the MSDN and VS.NET documenters).

The settings below govern how exactly the XML summary data is merged with the reflected meta-data and therefore govern what items will and will not appear in the final documentation.

These settings are shared by all of the current NDoc documenters. Particular documenters might include additional steps like compiling the transformed HTML into compiled help files. They will have additional settings that govern the details specific to the documenter's format.

Settings

Setting Description
(Global)
ReferencePaths The directories used to resolve assembly references.
Documentation Main Settings
AssemblyVersionInfo Determines what type of Assembly Version information is documented (if any).

Valid values are,

None No assembly info will be documented
Assembly Version This is the standard .Net version information specified in the AssemblyVersionAttribute.
File Version This is the file version specified in the AssemblyFileVersion attribute, as opposed to the /.Net standard Assembly Version. This type of version information is useful if an Assembly is to installed in the GAC, and the developer needs to avoid side-by-side versioning issues, but wishes to provide build version information...
AutoDocumentConstructors If true, automatic summary documentation for default constructors will be enabled. If no summary for a parameter-less constructor is present, the default constructor summary of Initializes a new instance of the ClassName class is inserted.
AutoPropertyBackerSummaries If true, the documenter will automatically add a summary for fields which look like they back (hold the value for) a property. The summary is only added if there is no existing summary, which gives you a way to opt out of this behavior in particular cases. Currently the naming conventions supported are such that fields _Length and length will be inferred to property Length.
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.

CopyrightHref The URI of a copyright notice. A link to this URI will be included with each topic.
CopyrightText A textual copyright notice that will be included with each topic.
FeedbackEmailAddress If an email address is supplied, a mailto link will be placed at the bottom of each page, pointing to this address.
Preliminary If true, NDoc will mark every topic as being preliminary documentation. Each topic will include a notice that the documentation is preliminary

The default notice is: [This is preliminary documentation and subject to change.]

SdkDocLanguge Specifies to which language version of the .NET Framework SDK documentation the links to system types will be pointing.
SdkDocVersion Specifies to which version of the .NET Framework SDK documentation the links to system types will be pointing.
UseNamespaceDocSummaries If true, the documenter will look for a class with the name NamespaceDoc in each namespace.  The summary from that class will then be used as the namespace summary. The class itself will not show up in the resulting documentation output.

You may want to use #if ... #endif together with conditional compilation constants to exclude the NamespaceDoc classes from release build assemblies.

UseNDocXmlFile When set, NDoc will use the specified XML file as input instead of reflecting the list of assemblies specified on the project.

Very useful for debugging documenters. Leave empty for normal usage.

Show Attributes
DocumentAttributes If true, custom attributes applied to types and members are documented the syntax portion of topics.
DocumentedAttributes When DocumentAttributes is set to true, this specifies which attributes/properties are visible. Empty to show all.

Format: '<attribute-name-starts-with>,<property-to-show>,<property-to-show>| <attribute-name-starts-with>,<property-to-show>,<property-to-show>|(etc...)'.

DocumentInheritedAttributes When DocumentAttributes is set to true, this specifies whether attributes inherited from base classes are visible
ShowTypeIdInAttributes Set this to true in order to output the TypeId property in the attributes.
Show Missing Documentation
ShowMissingParams If true, all parameters without /doc <param> comments will contain the phrase Missing Documentation in the generated documentation.
ShowMissingRemarks If true, all members without /doc <remarks> comments will contain the phrase Missing Documentation in the generated documentation.
ShowMissingReturns If true, all members without /doc <returns> comments will contain the phrase Missing Documentation in the generated documentation.
ShowMissingSummaries If true, all members without /doc <summary> comments will contain the phrase Missing Documentation in the generated documentation.
ShowMissingValues If true, all properties without /doc <value> comments will contain the phrase Missing Documentation in the generated documentation.
Visibility
DocumentEmptyNamespaces If true, empty namespaces will be included in the documentation. Normally, empty namespaces are not documented.
DocumentExplicitInterfaceImplementations If true, members that explicitly implement interfaces will be included in the documentation. Normally, these members are not documented.
DocumentInheritedFrameworkMembers If true, members inherited from .Net framework classes will be included in the documentation. By convention, this members are normally documented.

Note: if DocumentInheritedMembers is None, this setting will be ignored.

DocumentInheritedMembers This setting determines what types of inherited members are included in the documentation.

It has the following three options;

None no inherited members will be documented.
Instance Members only instance members will be documented. (This is the default).
Instance and Static Members both instance and static members will be documented.
DocumentInternals If true, types and members marked as internal will be included in the documentation.

Normally, internal items are not documented.

DocumentPrivates If true, types and members marked as private will be included in the documentation.  This is useful when using NDoc to create documentation intended for internal use.

Normally private items are not documented.

DocumentProtected If true, protected members will be included in the documentation.

Since protected members of non-internal types can be accessed outside of an assembly, this is true by default.

DocumentProtectedInternalAsProtected If true, NDoc will treat "protected internal" members as "protected" only.
DocumentSealedProtected If true, protected instance members of sealed classes will be documented. 

Note: For this setting to have any effect, DocumentProtected must also be true.

EditorBrowsableFilter Sets the level of filtering to apply on types/members marked with the EditorBrowsable attribute.

Warning: enabling this filter might result in invalid links in the documentation.

As of version 1.3 of NDoc, the <exclude/> tag is the preferred mechanism for suppressing the documentation of types or members.

SkipNamespacesWithoutSummaries If true, NDoc will not document namespaces that do not have an associated namespace summary.