CODEWITHSUNDEEP
c#visual-studiodocumentationnullableoptional-parameters
WiiMaxx
WiiMaxx

Reputation: 5420

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

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?

Upvotes: 5

Views: 2485

Answers (1)

DavidRR
DavidRR

Reputation: 19477

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

Upvotes: 3

Related Questions