Как создать cref для перегрузки метода в теге в C #?

ProgramBox

Как создать cref для перегрузки метода в теге в C #?

Post author:admin
Запись опубликована:26 апреля, 2023
Post category:Вопросы по программированию

#c# #visual-studio-2010 #overloading #sandcastle #xml-comments

#c# #xml-документация

Вопрос:

Я вижу в MSDN ссылки, такие как «Сравнение обычных перегрузок». Как я могу написать такую ссылку на C #?

Я пытался:

 <seealso cref="MyMethod">MyMethod Overloads</seealso>

Но компилятор выдает мне предупреждение о том, что это неоднозначная ссылка на метод, который имеет другие перегрузки.

(Вопрос для начинающих: действительно ли мне нужно писать этот тег для ссылки на перегрузки, или он автоматически генерируется процессорами документации?)

Ответ №1:

Чтобы настроить таргетинг на определенных участников, я полагаю, вы просто сопоставляете подпись:

 /// <seealso cref="Foo(int)"/>
static void Foo() { }
/// <seealso cref="Foo()"/>
/// <seealso cref="Foo(float)"/> <------ complains
static void Foo(int a) { }

Честно говоря, я не уверен, как сгенерировать ссылку «все перегрузки»; Я бы предположил, что любой разумный генератор сделал это автоматически.

1. Спасибо. Использует ли используемый вами генератор это автоматически?

2. На самом деле я не использую генератор; для моего использования подходит только xml (он используется как intellisense, так и reflector). Обычно мне не нужна отдельная документация.

Ответ №2:

Используя Sandcastle, это просто:

 <seealso cref="overloads:FullyQualifiedMyMethod">MyMethod Overloads</seealso>

FullyQualifiedMyMethod — это полный маршрут, необходимый для достижения перегрузки, включая пространства имен и классы, т.Е. System.Linq.Enumerable.Sum

Однако компилятор VB выдает предупреждение о том, что атрибут не может быть разрешен, которое можно игнорировать.

1. Тестирование с использованием SHFB 2014.5.31.0 показывает, что префикс должен быть o: , а не overloads: .

2. И компилятор C # (протестирован для lang версии 5.0) не выдает предупреждения при использовании o: , так что, возможно, это правильный путь.

3. Пробовал использовать see (а не seealso) и вообще не повезло. перегрузки: выдает предупреждение компилятора, а SHFB 14.5.31 игнорирует его. Также пробовал o: и M: и компилятор в порядке, но SHFB игнорирует их оба.

4. Я хотел бы сказать, что это должно быть принятым ответом, но опять же, OP не указал Sandcastle, так что, хм … возможно, нет. Все еще очень полезно 1.

5. Были проблемы со ссылкой на страницу перегрузок, но, наконец, я нашел правильный синтаксис: что сработало для меня, так это использование большой буквы «О», полного имени метода и без круглых скобок, вот так: <see cref="O:My.Long.Namespace.Class.Method">Link name</see> .

Ответ №3:

В документации Xml нет средств для ссылки на все перегрузки метода.

Самым популярным генератором документации для проектов на C # является Sandcastle. При необходимости автоматически создается ссылка на страницу списка перегрузок. Следовательно, на странице списка участников имя перегруженного метода появится только один раз, щелкнув по нему, вы перейдете на страницу списка перегрузок для этого метода, а оттуда к конкретной перегрузке.

Размещение ссылки на страницу списка перегрузок в документации Xml потребует глубокого знания используемого внешнего инструмента и, вероятно, не является хорошей идеей.

Если вам действительно это необходимо, то, возможно, одним из способов является использование привязки со специально сформированным идентификатором. Большинство генераторов документов предоставляют некоторые скрытые средства предварительной или последующей обработки сгенерированных файлов и должны дать вам возможность выбрать эти привязки и предоставить для них соответствующий href.

Кроме того, это может доставить больше проблем, чем того стоит 😉