Overview
NDoc3 uses a pluggable architecture, so it is also possible to generate your own, custom, documenters.
Generating the documentation consists of two basic steps:
- Merging the /doc XML summary with reflected meta-data from the assemblies.
- 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 NDoc3 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,
|
||||||
| 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 behaviour 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, NDoc3 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, NDoc3 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,
these members are normally documented.
Note: if DocumentInheritedMembers is False, this setting will be ignored. |
||||||
| DocumentInheritedMembers | If true, inherited members will be included in the documentation. By convention, these members are normally 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 NDoc3 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, NDoc3 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. |
||||||
| SkipNamespacesWithoutSummaries | If true, NDoc3 will not document namespaces that do not have an associated namespace summary. | ||||||