LS1011: Public Domain Contract Is Undocumented

LS1011 is a compiler check that reports a public type or member in Domain, the project that holds business rules, without XML documentation, which leaves readers guessing which business constraint, result, or failure it represents. This page states what the rule reports, where the warning sits, and how to document the contract.

Reference#

What the rule enforces#

LS1011 enforces Document every public Domain contract (litespec/backend/dotnet/domain#document-every-public-domain-contract). It runs in Domain only. Its category is LiteSpec.Domain. It reports a warning and is enabled by default, as the Analyzers overview describes.

What the rule reports#

The rule reports a public type or member without XML documentation. The rule checks classes, structs, interfaces, records, enums, delegates, ordinary methods, constructors, properties, events, and fields. It accepts a non-empty <summary> element or an <inheritdoc/> element, including /// lines in a build without a documentation file. The diagnostic sits on the identifier.

Failing example#

/// <summary>An order placed by a customer.</summary>
public sealed class Order
{
    public void Cancel()
    {
    }
}

Passing example#

/// <summary>An order placed by a customer.</summary>
public sealed class Order
{
    /// <summary>Cancels the order before it ships.</summary>
    public void Cancel()
    {
    }
}

How to fix#

Add a <summary> line that states the business constraint, result, or failure the member represents, or an <inheritdoc/> line when the contract inherits its documentation.

Notes#

What the rule ignores#

The rule does not report internal, private, or nested non-public contracts, overrides, or explicit interface implementations. Protected members of public types do need documentation. The rule does not run outside Domain.