Markdown document generator.
Get Started
$ dotnet add package dotnet-dotdocReadme
dotdoc
Reads XML document comments contained in the solution or project file and generates Markdown. It can be viewed on the Azure DevOps Wiki.
Usage
# add tool manifest
dotnet new tool-manifest
# install dotdoc locally
dotnet tool install dotnet-dotdoc
# create dotdoc Configuration
dotnet tool run dotdoc init
# generate document from solution/project
dotnet tool run dotdoc run
Commands
init
dotdoc init
Generate a .dotdoc file to the current directory containing the default settings. If there is a solution or project file in the current directory, it will automatically be set to the InputFile option.
run
dotdoc run
Reads the .dotdoc file in the current directory and generates a Markdown file.
Configuration
Configurations are set in the .dotdoc file.
{
"InputFileName": "src/sample.sln",
"ExcludeIdPatterns": [
"*:ExcludeNamespace.*",
"*:ExcludeNamespace",
"A:*.Tests"
],
"Accessibility": [
"Protected",
"Public",
"ProtectedInternal"
],
"OutputDir": "./apidocs",
"RemoveOutputDir": true,
"IgnoreEmptyNamespace": true,
"ExcludeDocumentClass": true,
"LogLevel": "Info",
"CreateAssembliesPage": true,
"AssembliesPage": {
"Name": "Assemblies",
"XmlDocumentFile": "assemblies.xml",
"RemoveAssembliesPageAndDir": true,
"Summary" : "Summary text for assemblies page"
}
}
InputFileName
Specify the name of the solution or project file to be read.
ExcludeIdPatterns
Specify the pattern of ID to exclude. The asterisk(*) matches any string. The format of the ID conforms to standard XML document comments.
The tool uses custom member identifiers.
| Character | Member type | Notes |
|---|---|---|
| A | assembly |
Accesibility
Specify the accesibility to be output.
Public: Generates documentation for 'public' access modifier.Protected: Generates documentation for 'protected' access modifier.Internal: Generates documentation for 'internal' access modifier.Private: Generates documentation for 'private' access modifier.ProtectedInternal: Generates documentation for 'protected internal' access modifier.PrivateProtected: Generates documentation for 'private protected' access modifier.
OutputDir
Specifies the destination directory. If it does not exist, it will be created.
RemoveOutputDir
Specifies whether the output directory is deleted before processing. Default is false.
IgnoreEmptyNamespace
Specifies whether or not to output namespaces that do not contain types.
ExcludeDocumentClass
Specify whether to exclude the AssemblyDoc and NamespaceDoc classes.
CreateAssembliesPage
Specify whether or not to output assemblies page. Default is false.
AssembliesPage.Name
Used for file and directory names and titles.
AssembliesPage.XmlDocumentFile
Specify the name of the XML file that defines the contents of the assemblies page. The XML format is the same as for ordinary document comments. The root element must be member.
<member>
<summary>This is summary text for assemblies page.</summary>
</member>
AssembliesPage.Summary
Specify summary text. This value overrides the value of the summary element specified in the XmlDocumentFile.
AssembliesPage.RemoveAssembliesPageAndDir
Specifies whether the output file and directory is deleted before processing. Default is false.
Documentation Xml Elements
Standard elements can be used to describe the document. However, in order to structure the document, the types of elements are classified.
Section Elements
Section elements may only be used for the root.
Block Elements
Block elements are available as child nodes of section elements. Elements other than the <para> element cannot be nested.
Inline Elements
Inline elements are available as childe nodes of section and block elements. Line breaks will be removed.
Miscellaneous Elements
Several special elements are available.
<inheritdoc> element
This element can help minimize the effort required to document complex APIs by allowing common documentation to be inherited from base types/members.
<inheritdoc [cref="member"] />
If this element is specified, it is inherited on a section element basis.
<overloads> element
This element is used to define the content that should appear on the auto-generated overloads topic for a given set of member overloads.
<overloads>summary comment</overloads>
<!--or-->
<overloads>
<summary>summary comment</summary>
<remarks>remarks comment</remarks>
<!--each section elements-->
</overloads>