dotnet-dotdoc 1.0.1

dotnet tool install --global dotnet-dotdoc --version 1.0.1                
This package contains a .NET tool you can call from the shell/command line.
dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local dotnet-dotdoc --version 1.0.1                
This package contains a .NET tool you can call from the shell/command line.
#tool dotnet:?package=dotnet-dotdoc&version=1.0.1                
nuke :add-package dotnet-dotdoc --version 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.

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>



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

Example

Product Compatible and additional computed target framework versions.
.NET net5.0 was computed.  net5.0-windows was computed.  net6.0 is compatible.  net6.0-android was computed.  net6.0-ios was computed.  net6.0-maccatalyst was computed.  net6.0-macos was computed.  net6.0-tvos was computed.  net6.0-windows was computed.  net7.0 was computed.  net7.0-android was computed.  net7.0-ios was computed.  net7.0-maccatalyst was computed.  net7.0-macos was computed.  net7.0-tvos was computed.  net7.0-windows was computed.  net8.0 was computed.  net8.0-android was computed.  net8.0-browser was computed.  net8.0-ios was computed.  net8.0-maccatalyst was computed.  net8.0-macos was computed.  net8.0-tvos was computed.  net8.0-windows was computed. 
.NET Core netcoreapp3.1 is compatible. 
Compatible target framework(s)
Included target framework(s) (in package)
Learn more about Target Frameworks and .NET Standard.

This package has no dependencies.

Version Downloads Last updated
1.0.1 857 10/14/2022
1.0.0 1,809 10/11/2022
0.2.0-preview.0.0.2 187 9/28/2022
0.2.0-preview.0.0 181 9/28/2022