使用C＃的XML注释cref属性和params语法

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?

在C#中,我试图使用 来引用包含params关键字的方法签名。我知道这会将参数列表转换为数组,但我甚至无法弄清楚如何在CREF属性中引用数组。我在搜索中找不到任何内容,也没有人知道任何想法。编译器在方括号上窒息。我已经尝试了各种不同的组合,使用花括号,使用Array类,但没有任何工作。有谁知道这个?

3 个解决方案

#1

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

ECMA 334标准PDF,附件E包含对XML文档注释的不错概述。您可以在以下位置下载标准:

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

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

具体来说,您需要从第496页开始的E.3.1节。

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

类似的内容也在MSDN上(虽然MSDN似乎在这个主题上导航很糟糕,但很难找到其他部分):

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

The equivalent to E.3.1:

相当于E.3.1:

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

You may also find Mono's documentation useful:

您可能还会发现Mono的文档很有用:

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

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

具体而言,“CREF FORMAT”部分涵盖了ID字符串约定。

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.

上面的ECMA-334标准PDF的URL链接到最新版本的标准。 2009年,这是该标准的第4版。但是,截至2017年12月,第5版是最新版,第4版的E.3.1部成为第5版的D.4.2部。

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

以下版本的ECMA-334标准可从以下页面下载:https://www.ecma-international.org/publications/standards/Ecma-334-arch.htm

#2

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

根据B.3.1 ID字符串格式文章,使用[方括号](带有可选的lowerbound:size说明符)来引用数组,但是如果你只想引用某个类型的数组(甚至是一个Object数组) ,你不能只写

<see cref="Object[]"/>

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

相反,您需要指定您使用T:前缀进行类型引用,例如

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

#3

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

你只需省略param关键字并输入如下类型:

/// <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);
    }
}