Using 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?

score 3 · Accepted Answer · edited May 23 '17 at 12:29

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).

Using with an optional and nullable parameter in XML documentation

1 Answers1