VisualStudio | summary with keyword 'null'

Question

I have a property which can be null. I want to documentate this in the summary and here is my problem.

cref

/// <summary>
/// Can be <see cref="null"/>.
/// </summary>
public object FooProperty;

ReSharper says, there is a Syntax Error, but the highlighting is working as expected!

cref nested

/// <summary>
/// Can be <see><cref>null</cref></see>.
/// </summary>
public object FooProperty;

When formating it to nested, the highligghting is not working anymore.

langword

/// <summary>
/// Can be <see langword="null"/>.
/// </summary>
public object FooProperty;

langword is working, but there is no intelliSense in VisualStudio.

Can someone please tell me what is the right way to documentate these keywords and IntelliSense support would be nice!

solution approach

• VisualStudio | CodeSnippet for inside comment/summary block (IntelliSense)

Answer 1

The langword is the way to go. You are right, there's no Intellisense support for this. It's probably because it's not officially recommended XML comment tag attribute. But the tools that can generate documentation from your comments, e.g. Sandcastle Help File Builder or VSdocman (disclaimer, I'm the developer of VSdocman) will recognize this syntax and will generate a special text. For example, VSdocman generates:

null reference (Nothing in Visual Basic)

The same applies to other reserved words, such as true, abstract, etc.

While Intellisense will not help you, VSdocman has a WYSIWYG comment editor which can assist you with more complex comments.

One more note to <see cref="null"/>. This will create a link to the class, method or property named null. This is not directly possible in C#, where you need to prepend @ before the name that is a reserved word:

/// <summary>
/// <see cref="@null"/>
/// </summary>
public class MyClass
{
    public void @null() {}
}

But this is perfectly valid in VB .NET:

''' <summary>
''' <see cref="null"/>
''' </summary>
Public Class MyClass
    ReadOnly Property null As String
End Class

Answer 2

In Visual Studio 2022 (v17.4.4), there is IntelliSense support for the <see langword="null"/> construct. It even shows a dropdown of the possible values of the langword attribute.