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
– Jodrell, Commented Apr 14, 2014 at 14:42
"XML Comment....gives me a syntax error" XML comments gives syntax error! I do not understand. — Bit
– Bit, Commented Apr 14, 2014 at 14:59
When I hover my mouse over the text [,] the tooltip says "syntax error". — openshac
– openshac, Commented Apr 14, 2014 at 15:05

Community · Accepted Answer · 2017-05-23 12:14:43Z

1

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.

edited May 23, 2017 at 12:14

CommunityBot

11 silver badge

answered Apr 14, 2014 at 15:04

Jodrell

35.8k6 gold badges94 silver badges131 bronze badges

Sign up to request clarification or add additional context in comments.

1 Comment

openshac Over a year ago

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.

Anthony · Accepted Answer · 2014-04-14 15:08:23Z

0

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>

answered Apr 14, 2014 at 15:08

Anthony

9,6119 gold badges49 silver badges75 bronze badges

Collectives™ on Stack Overflow

XML Comments for nullable 2D Array

2 Answers 2

1 Comment

Comments

Your Answer

Linked

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

1 Comment

Comments

Your Answer

Sign up or log in

Post as a guest

Linked

Related