XML Comments for nullable 2D Array

Question

How do I correct specify the XML Comments for a 2D array of nullable doubles? The following gives me syntax error.

/// <returns>The <see cref="double[,]"/>.</returns>
public double?[,] Get2DArray()
{
    ...
}

If it was just a 2D array of doubles I'd use:

/// <returns>The <see cref="double{T,T}]"/>.</returns>
public double[,] Get2DArray()
{
    ...
}

and if was just a single value I'd use:

/// <returns>The <see cref="Nullable{Double}"/>.</returns>
public static double? GetNullableDouble()
{

I can't seem to combine these two concepts to get the correct comments.

A multidimensional array is not generic so, I don't understand your question. More generally, use a jagged array (`double?[][]`), the .net implementation of jagged arrays is superior in multiple ways. — Jodrell, Apr 14 '14 at 14:42
"XML Comment....gives me a syntax error" XML comments gives syntax error! I do not understand. — Bit, Apr 14 '14 at 14:59
When I hover my mouse over the text [,] the tooltip says "syntax error". — openshac, Apr 14 '14 at 15:05

score 1 · Accepted Answer · edited May 23 '17 at 12:14

After reading here, perhaps you want,

/// <summary>
/// Gets the 2D Array
/// </summary>
/// <returns>The <see cref="T:double?[,]"/>.</returns>
public double?[,] Get2DArray()
{
    ...
}

As commented, rather than a multi-dimensional array (double?[,]) you should consider something jagged, the internal .Net implementation is superior. Additionaly, if you think of interfaces as promises, you should make the smallest possible promise, they are easier to keep.

Perhaps,

/// <summary>
/// Gets the 2D Array
/// </summary>
/// <returns>
/// The <see cref="T:IEnumerable{IEnumerable{double?}}"/> data.
/// </returns>    
public IEnumerable<IEnumerable<double?>> GetData()
{
    ...
}

would suffice.

When I hover over the T:double?[,] in the function header the tooltip says "Cannot resolve symbol 'T:double?[,]'". However the signature seems to be correct from the calling code. — openshac, Apr 14 '14 at 15:12

score 0 · Answer 2 · answered Apr 14 '14 at 15:08

The problem is that there is no generic array type, so there is nothing to reference. I believe this is done using compiler magic, but that's beyond my knowledge.

I looked through a bunch of the core .NET source to see if any of the cref values which talk about arrays use any generic reference and I'm not finding anything. Everything using <see cref="T:System.Array"/>.

I would recommend that your best option is to use the following format:

<returns>The 2-dimentional <see cref="System.Array"/> of <see cref="System.Nullable{System.Double}" />.</returns>

XML Comments for nullable 2D Array

2 Answers2