Using C#'s xml comment cref attribute with params syntax.

Question

In C#, I am trying to use <see cref="blah"/> to reference a method signature that contains the params keyword. I know this converts the parameter list to an array, but I can't even figure out how to refer to an array in a CREF attribute. I am finding nothing in my searches and no one I know has any idea, either. The compiler is choking on the square brackets. I've tried all kinds of different combinations, using curly braces, using the Array class, but nothing is working. Does anyone know this?

Answer 1

You just leave out the param keyword and put in the type like this:

    /// <summary>
    /// <see cref="Method(string[])"/>
    /// </summary>
    public static void Main()
    {
        Method("String1", "String2");
    }

    public static void Method(params string[] values)
    {
        foreach (string value in values)
        {
            Console.WriteLine(value);
        }
    }

Answer 2

The ECMA 334 Standard PDF, Annex E contains a decent overview of XML Documentation comments. You can download the standard at:

http://www.ecma-international.org/publications/standards/Ecma-334.htm

Specifically, you'll want section E.3.1, starting on page 496.

Similar content is also at MSDN (though MSDN seems to have terrible navigation on this topic, making it difficult to find the other sections):

http://msdn.microsoft.com/en-us/library/aa664787(VS.71).aspx

The equivalent to E.3.1:

http://msdn.microsoft.com/en-us/library/aa664807(VS.71).aspx

You may also find Mono's documentation useful:

http://www.go-mono.com/docs/index.aspx?tlink=29@man%3amdoc(5)

Specfically, the "CREF FORMAT" section covers the ID string conventions.

Answer 3

According to the B.3.1 ID string format article, referencing an array is done with [square brackets] (with optional lowerbound:size specifiers) but if you just want to refer to an array of a certain type (or even an Object array), you can't just write

<see cref="Object[]"/>

instead you need to specify you're making a type reference with the T: prefix, like

<see cref="T:Object[]"/>

This does not seem to apply when referencing a specific overload of a method, such as

<seealso cref="String.Join(String, String[])"/>