BRO1618: Write a C# keyword in documentation as `<see langword="..."/>`¶

A C# keyword alone in <c>, such as <c>null</c>, <c>true</c> or <c>static</c>, is written <see langword="null"/>. Not a StyleCop rule; Meziantou's MA0154 checks the same.

Example¶

Before¶

public class Cache
{
    /// <summary>Finds an item.</summary>
    /// <param name="key">The key.</param>
    /// <returns>The item, or <c>null</c> when it isn't cached.</returns>
    public object? Find(string key) => null;
}

After¶

public class Cache
{
    /// <summary>Finds an item.</summary>
    /// <param name="key">The key.</param>
    /// <returns>The item, or <see langword="null"/> when it isn't cached.</returns>
    public object? Find(string key) => null;
}

Why¶

<see langword="null"/> is what Microsoft's documentation uses for keywords: documentation tools link it to the keyword's page, and Visual Studio shows it like a keyword. <c>null</c> is only code-formatted text. One form for keywords also keeps the documentation consistent.

How the fix works¶

The fix replaces the whole <c> element with <see langword="keyword"/>.

This rule reads documentation as XML, which the compiler only does when the project generates documentation (<GenerateDocumentationFile>true</GenerateDocumentationFile>), like the other documentation rules.

Which keywords¶

Every reserved C# keyword (null, true, false, void, static, abstract, sealed, int, string, ...), plus the contextual keywords Meziantou's MA0154 takes because they're unlikely to be an identifier: async, await, dynamic, init, nameof, nint, nuint, partial, record, required, scoped and var. Other contextual keywords (value, get, set, add, from, select, ...) are common words and names, so they're left alone.

Not reported¶

Anything more than one keyword in the <c>: <c>null!</c>, <c>x is null</c>, <c> null </c> (spaces), or other elements inside it.
A <c> with attributes (<c lang="cs">null</c>).
Inside <code>: a code sample stays as written.
Different case (<c>Null</c>): C# keywords are lower case.

BRO1618: Write a C# keyword in documentation as <see langword="..."/>¶