Search code examples
visual-studiodocumentationresharpersummary

VisualStudio | summary with keyword 'null'

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!

Syntax Error highlight

cref nested

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

not working

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

Solution

  • 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