Использование атрибута cref комментария XML C# с синтаксисом параметров
-
11-09-2019 - |
Вопрос
В C# я пытаюсь использовать <see cref="blah"/> для ссылки на сигнатуру метода, содержащую ключевое слово params.Я знаю, что это преобразует список параметров в массив, но я даже не могу понять, как ссылаться на массив в атрибуте CREF.Я ничего не нахожу в своих поисках, и никто из моих знакомых не имеет ни малейшего представления об этом.Компилятор задыхается от квадратных скобок.Я пробовал самые разные комбинации, используя фигурные скобки, класс Array, но ничего не работает.Кто-нибудь это знает?
Решение
Стандарт PDF ECMA 334, Приложение E содержит достойный обзор комментариев XML-документации.Скачать стандарт можно по адресу:
http://www.ecma-international.org/publications/standards/Ecma-334.htm
В частности, вам понадобится раздел E.3.1, начиная со страницы 496.
Аналогичный контент также есть в MSDN (хотя MSDN, похоже, имеет ужасную навигацию по этой теме, что затрудняет поиск других разделов):
http://msdn.microsoft.com/en-us/library/aa664787(VS.71).aspx
Эквивалент E.3.1:
http://msdn.microsoft.com/en-us/library/aa664807(VS.71).aspx
Вам также может пригодиться документация Mono:
http://www.go-mono.com/docs/index.aspx?tlink=29@man%3amdoc(5)
В частности, раздел «CREF FORMAT» описывает соглашения о строках идентификаторов.
Обновление 23 мая 2018 г.
URL-адрес PDF-файла стандарта ECMA-334 выше содержит ссылку на последнюю редакцию стандарта.В 2009 году это было четвертое издание стандарта.Однако по состоянию на декабрь 2017 года актуальной является 5-я редакция, а раздел E.3.1 4-й редакции стал разделом D.4.2 5-й редакции.
Предыдущие версии стандарта ECMA-334 доступны для загрузки на следующей странице: https://www.ecma-international.org/publications/standards/Ecma-334-arch.htm
Другие советы
Согласно B.3.1 Формат строки идентификатора статье ссылка на массив осуществляется с помощью [квадратных скобок] (с необязательным lowerbound:size
спецификаторы), но если вы просто хотите сослаться на массив определенного типа (или даже на массив объектов), вы не можете просто написать
<see cref="Object[]"/>
вместо этого вам нужно указать, что вы делаете ссылку на тип с помощью T:
префикс, например
<see cref="T:Object[]"/>
Похоже, это не применимо при ссылке на конкретную перегрузку метода, например
<seealso cref="String.Join(String, String[])"/>
Вы просто опускаете ключевое слово 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);
}
}