Справочные префиксы в XML-документации .NET

Question

Я пытался полностью документировать все типы, методы, свойства и т. д.библиотеки классов с использованием комментариев XML, но столкнулся с любопытным эффектом, связанным с cref атрибут (используется see теги, например).Следуя совету эта страница MSDN а также следуя различным другим примерам на MSDN и других веб-сайтах, кажется, что всякий раз, когда кто-то указывает ссылочное значение, используя cref тегу, перед ним должен быть указан определенный маркер, классифицирующий ссылку (например, «T:» для типа и «M:» для метода).

Однако, используя Microsoft Sandcastle, я заметил, что отсутствие этих префиксов влияет на сгенерированную документацию (в данном случае файл справки CHM).Включая префиксы (я думаю, во всех ситуациях) ссылка отображается на странице как жирный текст...Тем не менее, без учета префикса ссылка отображается как привязка (ссылка) на соответствующую страницу в ссылке API.Мне кажется довольно странным, что рекомендуемый метод префикса (всех?) ссылок дает наименее полезный результат - почему ссылка должна быть выделена жирным шрифтом в одном случае и связана в другом?Я был бы признателен, если бы кто-нибудь мог пролить свет на это.

Answer 1

Похоже, это был ошибка в замке из песка

Какую версию Sandcastle вы используете?

Тем не менее недавние обсуждения кажется, указывает на то, что, по крайней мере, для системных типов, предлагаемый метод состоит в том, чтобы фактически избегать использования полных имен, поскольку в примерах, приведенных в этом ответе, отсутствует буква T:И м:Поэтому Ваше замешательство не является чем-то неожиданным или необычным.

Эта документация настоятельно подразумевает, что компилятор, где он может определить, на какой тип/метод/константу вы указываете, вставляет префиксы за вас.Вы проверили это в XML?