SA1600.md

SA1600

TypeName	SA1600ElementsMustBeDocumented
CheckId	SA1600
Category	Documentation Rules

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.

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.

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