SZARRAY encoding in XML documentation ID string

[KalleOlaviNiemitalo]

Describe the bug

§D.4.2 ID string format specifies that, when an array type is encoded in the ID string, the lower bound and size of each dimension is also encoded if known:

csharpstandard/standard/documentation-comments.md

Line 642 in 721ef29

- Arguments that are arrays are represented as `[` *lowerbound* `:` *size* `,` … `,` *lowerbound* `:` *size* `]` where the number of commas is the rank less one, and the lower bounds and size of each dimension, if known, are represented in decimal. If a lower bound or size is not specified, it is omitted. If the lower bound and size for a particular dimension are omitted, the “`:`” is omitted as well. Jagged arrays are represented by one “`[]`” per level.

However, one-dimensional zero-bound unspecified-size arrays (ELEMENT_TYPE_SZARRAY in ECMA-335) are actually encoded with just [] rather than [0:].

Also, multidimensional arrays appear to have 0: for each dimension. According to §16.1, C# array types have a lower bound of zero in every dimension. It might be worth adding a note about this to §D.4.2, especially because the System.Type and System.Reflection.ParameterInfo APIs do not provide methods for querying the bounds of an array type, although System.Array has methods for querying the bounds of an array instance.

csharpstandard/standard/arrays.md

Line 7 in 721ef29

An array has a rank that determines the number of indices associated with each array element. The rank of an array is also referred to as the dimensions of the array. An array with a rank of one is called a ***single-dimensional array***. An array with a rank greater than one is called a ***multi-dimensional array***. Specific sized multi-dimensional arrays are often referred to as two-dimensional arrays, three-dimensional arrays, and so on. Each dimension of an array has an associated length that is an integral number greater than or equal to zero. The dimension lengths are not part of the type of the array, but rather are established when an instance of the array type is created at run-time. The length of a dimension determines the valid range of indices for that dimension: For a dimension of length `N`, indices can range from `0` to `N – 1` inclusive. The total number of elements in an array is the product of the lengths of each dimension in the array. If one or more of the dimensions of an array have a length of zero, the array is said to be empty.

(I suppose it might be possible to define a non-zero-bound array parameter in a different programming language and reference that with the C# XML documentation comments cref attribute, in which case the C# compiler might generate an ID string with the non-zero-bound syntax.)

Example

ArrayDoc.csproj:

<Project Sdk="Microsoft.NET.Sdk">

  <PropertyGroup>
    <TargetFramework>net6.0</TargetFramework>
    <LangVersion>6.0</LangVersion>
    <GenerateDocumentationFile>true</GenerateDocumentationFile>
  </PropertyGroup>

</Project>

ArrayDoc.cs:

public abstract class ArrayDoc
{
    /// <summary>Some method</summary>
    protected abstract void M(int[] a, int[,] b);
}

Generated ArrayDoc.xml:

<?xml version="1.0"?>
<doc>
    <assembly>
        <name>ArrayDoc</name>
    </assembly>
    <members>
        <member name="M:ArrayDoc.M(System.Int32[],System.Int32[0:,0:])">
            <summary>Some method</summary>
        </member>
    </members>
</doc>

Note the ID string is not M:ArrayDoc.M(System.Int32[0:],System.Int32[0:,0:]).

Expected behavior

Declare that a one-dimensional, zero-bound array type is encoded in the ID string as [] rather than [0:].

Perhaps add a note saying that array types defined in C# always have a lower bound of zero, with a cross reference to §16.1.

Additional context

I vaguely recall that a one-dimensional, unknown-lower-bound array type might be encoded as [*], but I don't remember where I saw that. It's not ECMA-335 §II.14.2, which uses [...] instead.

---

Associated WorkItem - 178981

[svick]

I vaguely recall that a one-dimensional, unknown-lower-bound array type might be encoded as [*], but I don't remember where I saw that.

It's Type.ToString() that does that:

typeof(int).MakeArrayType().ToString() // SZARRAY, returns "System.Int32[]"
typeof(int).MakeArrayType(1).ToString() // one-dimensional, zero-bound MDARRAY, returns "System.Int32[*]"