Using <see cref=“”/> with an optional and nullable parameter in XML documentation

Question

While writing the XML documentation for my program I have run into a problem documenting this method:

internal void MethodB(int i, DateTime? date = null);

The problem I am having is specfic to the date parameter. As you can see, it is optional as well as nullable . Here is how I tried to document this method:

/// <summary>
/// This method uses <see cref="MethodB(Int32, System.DateTime)"/> internally
/// todo some stuff.
/// </summary>

Specifically, I am getting a compiler warning that indicates that the value of cref could not be resolved.

How can I fix my XML documentation comment so that it will compile without this warning?

Answer 1

Try indicating that the System.DateTime parameter is nullable:

using System;

/// <summary>
/// This method uses <see cref="MethodB(Int32, DateTime?)"/>
/// internally to do some stuff...
/// </summary>

Edit: And as the OP @WiiMaxx later discovered, there is an alternative syntax:

/// <summary>
/// This method uses <see cref="MethodB(Int32, Nullable{DateTime})"/>
/// internally to do some stuff...
/// </summary>

Note also that the language-specific type int can be used as an alternative to the system type Int32 (and some would argue that int is preferable):

/// <summary>
/// This method uses <see cref="MethodB(int, DateTime?)"/>
/// internally to do some stuff...
/// </summary>

See: int or Int32? Should I care? and What's the difference between String and string? .

Finally, regardless whether the XML documentation comment includes Int32 or int , Int32 will appear in the generated documentation (which is not programming language-specific).