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