Using C#'s XML comment cref attribute with params syntax

99封情书 提交于 2019-11-30 00:28:07
jonp

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.

Update 2018/05/23

The URL for the ECMA-334 standard PDF above links to the latest edition of the standard. In 2009, that was the 4th edition of the standard. However, as of December 2017, the 5th edition is current, and section E.3.1 from the 4th edition became section D.4.2 in the 5th edition.

The previous versions of the ECMA-334 standard are available for download from the following page: https://www.ecma-international.org/publications/standards/Ecma-334-arch.htm

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[])"/>

Martin Brown

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);
    }
}
易学教程内所有资源均来自网络或用户发布的内容,如有违反法律规定的内容欢迎反馈
该文章没有解决你所遇到的问题?点击提问,说说你的问题,让更多的人一起探讨吧!