dotnet-dotdoc 1.0.1

<img src="./assets/logo/logo.svg" alt="logo" height="192px" style="margin-bottom:2rem;" />

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.

• <summary>
• <remarks>
• <example>
• <param>
• <typeparam>
• <returns>
• <value>

Block Elements

Block elements are available as child nodes of section elements. Elements other than the <para> element cannot be nested.

• <para>
• <list>: If the Type attribute is not specified, it is not displayed.
• <code>

Inline Elements

Inline elements are available as childe nodes of section and block elements. Line breaks will be removed.

• <c>
• <see>
• <paramref>
• <typeparamref>

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>



<overloads>
    <summary>summary comment</summary>
    <remarks>remarks comment</remarks>
    
</overloads>

Example

• dotdoc apidocs