Table of Contents

SA1600: Elements should be documented

Cause

A C# code element is missing a documentation header.

Rule description

C# syntax provides a mechanism for inserting documentation for classes and elements directly into the code, through the use of Xml documentation headers. For an introduction to these headers and a description of the header syntax, see the following article: https://docs.microsoft.com/en-us/dotnet/csharp/programming-guide/xmldoc/xml-documentation-comments.

A violation of this rule occurs if an element is completely missing a documentation header, or if the header is empty. In C# the following types of elements can have documentation headers: classes, constructors, delegates, enums, events, finalizers, indexers, interfaces, methods, properties, records, and structs.

Records and primary constructors

Record classes and record structs follow the same expectations as classes and structs. Positional parameters in a record declaration become properties; when documenting a public record, include <param> tags for those parameters in addition to the <summary> text for the record itself.

SA1600 reports each positional parameter without a matching <param name="..."> tag at the parameter name. Parameter names are case-sensitive. These checks follow the documentation settings and the record's effective accessibility, including for partial records. Documentation supplied through <include> or <inheritdoc> is supported. Empty parameter documentation is checked by SA1614 rather than SA1600.

For example:

/// <summary>Record.</summary>
/// <param name="Parameter">The value of the generated property.</param>
public record MyRecord(int Parameter);

Primary constructor parameters of non-record classes and structs are constructor parameters, not properties. Missing parameter tags for these declarations are checked by SA1611, not SA1600.

Default interface members

Interface members are implicitly public unless otherwise specified. Default interface members (methods, properties, indexers, events, etc. that include implementations) follow these rules:

  • Public interface members still require documentation when interfaces are configured to be documented (the default).
  • Non-public interface members (such as private default implementations) follow the documentPrivateElements setting. When documentPrivateElements is false (default), these members do not require documentation.

Explicit interface implementations in classes do not require separate documentation; they inherit documentation from the interface definition.

Partial types, methods, properties, indexers, constructors and events are reported by SA1601 instead. For partial members, documenting any one part of the member is enough: an undocumented part is not reported by either rule when another part of the same member is documented, and SA1601 only reports it when no part is documented.

How to fix violations

To fix a violation of this rule, add or fill-in a documentation header for the element.

The following example shows a method with a valid documentation header:

/// <summary>
/// Joins a first name and a last name together into a single string.
/// </summary>
/// <param name="firstName">The first name to join.</param>
/// <param name="lastName">The last name to join.</param>
/// <returns>The joined names.</returns>
public string JoinNames(string firstName, string lastName)
{
    return firstName + " " + lastName;
}

The next example shows a method that inherits documentation from a method in the base class:

/// <summary>
/// Example base class.
/// </summary>
class Vehicle 
{
  /// <summary>
  /// Accelerates the vehicle.
  /// </summary>
  public virtual void Accelerate()
  {                    
    Console.WriteLine("Vehicle is accelerating");
  }
}

/// <summary>
/// Example derived class.
/// </summary>
class Car : Vehicle
{
  /// <inheritdoc/>
  public override void Accelerate()
  {
    Console.Writeline("Car is accelerating");
  }
}

Starting with C# 9, overrides can declare covariant return types. Documentation can still be inherited directly from the base member using <inheritdoc/>:

/// <summary>
/// Base factory.
/// </summary>
class WidgetFactory
{
  /// <summary>
  /// Creates a widget.
  /// </summary>
  /// <returns>The newly created <see cref="Widget"/>.</returns>
  public virtual Widget Create() => new Widget();
}

/// <summary>
/// Specialized factory.
/// </summary>
class FancyWidgetFactory : WidgetFactory
{
  /// <inheritdoc/>
  public override FancyWidget Create() => new FancyWidget();
}

How to suppress violations

[SuppressMessage("StyleCop.CSharp.DocumentationRules", "SA1600:ElementsMustBeDocumented", Justification = "Reviewed.")]

#pragma warning disable SA1600 // ElementsMustBeDocumented
#pragma warning restore SA1600 // ElementsMustBeDocumented
Edit this page