p1va / dotnet-document

A tool for auto-generating XML documentation for your C# code

dotnet-document

A cross platform tool that auto generates an XML doc starting point for your C# codebase.

Thanks to Microsoft.CodeAnalysis.CSharp this tool is able to identify undocumented members and to generate a meaningful XML doc by humanizing member names.

Before	After

Installation

The tool can be installed globally via Nuget by running

dotnet tool install --global dotnet-document --version 0.1.9-alpha

👉 When installing pre releases the version has to be explicitly specified

How to run

Apply doc

To run the tool invoke dotnet document apply

# Documents all *.cs files in the current dir and all sub dirs 
dotnet document apply

# Documents the specified .cs file
dotnet document apply ./src/folder/MyClass.cs

# Documents all *.cs files in the specified dir and all sub dirs 
dotnet document apply ./src/folder/

# Documents all *.cs files in the specified solution
dotnet document apply ./src/solution.sln

# Documents all *.cs files in the specified project
dotnet document apply ./src/folder/project.csproj

Dry run

To test the command without saving changes on disk a dry run option is available.

In case of undocumented members a non-zero exit code is returned so that it is possible to warn about it during CI.

dotnet document apply --dry-run

Configuration

The tool can be configured so that the generated XML documentation meets the project guidelines.

Default configuration

The default configuration is used when no config file specified. It can be viewed by invoking

dotnet document config --default

Customizing configuration

To customize the configuration, simply save the default one somewhere and use your preferred editor to update it.

dotnet document config --default > ~/my-dotnet-document.yaml

Custom configuration path can be provided either by setting a DOTNET_DOCUMENT_CONFIG_FILE env variable or by passing the -c argument when calling the apply command. The latter overrides the first.

dotnet document apply \
  -c ~/my-dotnet-document.yaml \
  ./src/folder/

To double check which configuration is being used, invoke

dotnet document config

👉 Folder based configuration discovery is not yet supported

Acknowledgments

• Humanizer - Used for humanizing member names
• Ensure.That - Used as a guard clause
• FluentAssertions - Used for wrinting better assertions
• Moq4 - A mocking library for easier testing
• xUnit - The test framework

dotnet-document's Issues

Support dotnet 6

PS D:\DataWenfeng\XXXX> dotnet tool install --global dotnet-document --version 0.1.4-alpha
You can invoke the tool using the following command: dotnet-document
Tool 'dotnet-document' (version '0.1.4-alpha') was successfully installed.

PS D:\DataWenfeng\XXXX> dotnet document apply
You must install or update .NET to run this application.

App: C:\Users\wenfeng\.dotnet\tools\dotnet-document.exe
Architecture: x64
Framework: 'Microsoft.NETCore.App', version '5.0.0' (x64)
.NET location: C:\Program Files\dotnet\

The following frameworks were found:
  6.0.6 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]
  6.0.7 at [C:\Program Files\dotnet\shared\Microsoft.NETCore.App]

Learn about framework resolution:
https://aka.ms/dotnet/app-launch-failed

To install missing framework, download:
https://aka.ms/dotnet-core-applaunch?framework=Microsoft.NETCore.App&framework_version=5.0.0&arch=x64&rid=win10-x64

Add option to not add documentation for private methods/classes

Add `<typeparam>` tag support

We have enabled type_parameters in config, but it does not work. I mean type_parameters for classes. Does it work if I add this config parameter here? If it will, I would like to know what config parameters are available at all. I think all parameters should be listed in the default config.

Support via Patreon

Can I support you via Patreon?

Add configuration event handlers methods

Problem

dotnet-document does not have configuration for event handlers

Method:

private void OnCancelKeyPress(object sender, ConsoleCancelEventArgs e)

Summary written by dotnet-document for this method:

/// <summary>
/// Ons the cancel key press using the specified sender.
/// </summary>

Bad summary of class

Hi, thanks for this project.

This is my case :

input :

#region Licensing

// Copyright (c) XXX
// All rights reserved.

#endregion

#region Usings

using System.Diagnostics;

#endregion

namespace X.XX.Web.Api.Bases;

public static class DotEnv
{
    public static void Load(string filePath, string? prefix)
    {
        if (!File.Exists(filePath)) return;

        foreach (string line in File.ReadAllLines(filePath))
        {
            string[] parts = line.Split(
                '=',
                StringSplitOptions.RemoveEmptyEntries);

            if (parts.Length != 2) continue;

            Trace.WriteLine($"DotEnv {parts[0]} = {parts[1]}");

            Environment.SetEnvironmentVariable($"{prefix}{parts[0]}", parts[1]);
        }
    }
}

output :

#region Licensing

// Copyright (c) XXX
// All rights reserved.

#endregion

#region Usings

using System.Diagnostics;

#endregion

namespace X.XX.Web.Api.Bases;

/// <summary>

/// The dot env class

/// </summary>

public static class DotEnv
{
    /// <summary>
    /// Loads the file path
    /// </summary>
    /// <param name="filePath">The file path</param>
    /// <param name="prefix">The prefix</param>
    public static void Load(string filePath, string? prefix)
    {
        if (!File.Exists(filePath)) return;

        foreach (string line in File.ReadAllLines(filePath))
        {
            string[] parts = line.Split(
                '=',
                StringSplitOptions.RemoveEmptyEntries);

            if (parts.Length != 2) continue;

            Trace.WriteLine($"DotEnv {parts[0]} = {parts[1]}");

            Environment.SetEnvironmentVariable($"{prefix}{parts[0]}", parts[1]);
        }
    }
}

problem :

We can see the summary of the class has new lines, and breaks C# Xml doc, at least on vs22.

/// <summary>

/// The dot env class

/// </summary>

[Bug] Multiline Problem with seealso and base classes

Description

When the signature of a class has multiline base classes the Documentation does not generate comment slashes.

Expected Behaviour

The new lines should start with comment slashes (///) or the \n should be removed

Actual Behaviour

New lines do not start as a comment an break during build

Example (fictional but should work)

public class foo : bar<
    a,
    b
>
{
    ...
}

Is this the way to configure field doc template?

While applying documents I can see logline:
...: Field declaration '_myField' has no document and documentation is being generated.
but in the config which I got from dotnet document config > my-config.yaml I couldn't find anything to make the tool skip field documentation as it is required in my project.

Need to be able to save file in UTF-8 encoding

configure my config file so only classes and functions are commented

Thank you for this cool tool!
Quick question:
I copied the default config file and modified it to disable commenting enum members.

enum_member:
  summary:
    template: The {name} {enum}
    new_line: true
  enabled: false
  required: false

using dotnet document config shows that the change has taken effect since the lines enabled and required are no longer printed:

enum_member:
  summary:
    template: The {name} {enum}
    new_line: true
default_member:

However, when I run dotnet document apply, my enum members are still being commented. I also tried this with the default_members properties etc. with the same result.
How do I have to configure my config file so only classes and functions are commented and the rest (e.g. enum members) are left alone?