/mddox

Markdown documentation generator tool

Primary LanguageC#MIT LicenseMIT

NuGet version NuGet

ATTENTION: Some command line changes were introduced since version 0.9.0. See options --all-recursive, --recursive and --ignore-attribute

mddox

Global tool that creates markdown documentation using reflection and XML comments extracted from the source code by the compiler.

Sample documentation generated by the tool

MSDN page on XML documentation comments

Installation

dotnet tool install -g loxsmoke.mddox

Uninstallation

dotnet tool uninstall -g loxsmoke.mddox

Usage

mddox
Usage: mddox <assembly> [optional-parameters]

<assembly>   - The name of the assembly to document.

Optional parameters:

Short format Long format Comment
-o output_md --output output_md The name of the markdown output file.
-f format --format format The markdown file format. Valid values: github,bitbucket.
--all-recursive Step into all referenced assemblies recursively.
-r assembly --recursive assembly Step into specified referenced assemblies recursively.
Specify one or more assembly names separated by spaces.
-m --ignore-methods Do not generate documentation for methods and constructors.
Useful for POCO documentation.
-d --method-details Generate detailed documentation for methods and constructors.
Setting has no effect if --ignore-methods is specified.
-a name --ignore-attribute name Do not generate documentation for properties with specified custom attribute(s).
For example JsonIgnoreAttribute
More than one space-separate attribute can be specified.
-t name --type name Document only the specified type and all types referenced by it.
-s view --msdn view Generate links to the MSDN documentation for System.* and Microsoft.* types.
The documentation pages are located at this site https://docs.microsoft.com
View specifies what version of the type to show. Use latest, netcore-3.1, or net-5.0
-i "title" --title "title" Document title. Use {assembly} and {version} in the format string to insert the name of the assembly and assembly version.
-n --no-title Do not write the "created by mddox at date" in the markdown file.
-v --verbose Print some debug info when generating documentation. It may help troubleshooting some issues such as missing type information of referenced assemblies.

For best results enable XML documentation build switch in your project and use publish build to get all referenced assemblies in one folder.

Documenting all types of one assembly

mddox MyAssembly.dll

Documenting only fields and properties of all types in assembly

mddox MyAssembly.dll --ignore-methods

Documenting types that do not have specified custom attributes

mddox MyAssembly.dll --ignore-attribute JsonIgnoreAttribute --ignore-attribute XmlIgnore

Document one type and all referenced types from different assemblies

mddox MyAssembly.dll --type ClassToDocument --recursive ReferencedAssembly1.dll --recursive ReferencedAssembly2.dll