Комментарии XML - Документация MSDN Раздел "Примечание" - как вы продублируете это?
По сути, в онлайн-справке MSDN я часто сталкиваюсь с разделом "ПРИМЕЧАНИЕ", но никак не могу понять, как получить такой же вывод. Видимо нет <note> тег. Кто-нибудь знает, как заставить это работать?
IDictionary (TKey, TValue) - в этом примере, если вы перейдете в раздел замечаний, вы увидите, о чем я говорю.
Я использую Sandcastle Help File Builder.
3 ответа
На самом деле, и Sandcastle, и Sandcastle Help File Builder поддерживают <note> элемент, хотя он очень хорошо спрятан!:-) Это только в двух местах, которые мне известны:
- Справочник по комментариям к документации по XML от Dyncity... который, по-видимому, больше не доступен в Интернете - раньше это была http://www.dynicity.com/downloads/default.aspx.
- Настенная диаграмма, сопровождающая мою статью на Simple-Talk.com, озаглавленную " Укрощение песочного замка : руководство программиста.NET по документированию вашего кода". Обратите внимание, что в статье есть ссылка для перехода к настенной диаграмме, но она находится в самом низу статьи, поэтому я дал ссылки на обе статьи здесь. (У меня есть ссылка на руководство Dyncity в моей статье; я свяжусь с редакцией, чтобы узнать, не хотят ли они разместить локальную копию ныне осиротевшего руководства Dyncity и опубликовать обновление здесь, если они это сделают.)
Вот обо всей документации для <note> элемент. (Это из моей настенной диаграммы; руководство Dyncity говорит, по сути, то же самое, но гораздо менее лаконично.)
Эта неадекватная документация, к сожалению, все, что я нашел о <note>, Поэтому я провел небольшую пробную версию, вставив каждый тип заметки в раздел " Примечания ". Вот что он произвел:
То есть с type="caution" Вы получаете значок и метку предостережения, в то время как два других значения атрибута типа дают тот же значок и метку заметки в моем конкретном примере. Я подозреваю, что могут быть другие аспекты его использования, глубоко скрытые в подлеске.
Чтобы расширить комментарий кубра к ответу Бобби, на самом деле теперь есть достаточно обширная документация по элементу Note в Sandcastle.
Существует четыре категории заметок, которые вы можете добавить к любому другому элементу xml по умолчанию, такому как примечание или элементы сводки. Это общие, предостерегающие, безопасность или язык. Основное различие между ними заключается в типе значка, который они дают для заметки, и названия, которое примечание имеет рядом со значком. Вы можете увидеть полный список всех этих типов заметок здесь.
Следующий код сгенерировал для меня следующий результат:
/// <remarks>
/// <note type="note">
/// This is a note in a remark. It is a General note.
/// </note>
/// <note type="tip">
/// This is a tip note in a remark. It is a General note.
/// </note>
/// <note type="implement">
/// This is a implement note in a remark. It is a General note.
/// </note>
/// <note type="caller">
/// This is a caller note in a remark. It is a General note.
/// </note>
/// <note type="inherit">
/// This is a inherit note in a remark. It is a General note.
/// </note>
/// <note type="caution">
/// This is a caution note in a remark. It is a Cautionary note.
/// </note>
/// <note type="important">
/// This is a important note in a remark. It is a Cautionary note.
/// </note>
/// <note type="security">
/// This is a security note in a remark. It is a Security note.
/// </note>
/// <note type="cs">
/// This is a cs note in a remark. It is a Language note.
/// </note>
/// </remarks>
Результат: сгенерированный файл справки
Существует очень мало документации по Sandcastle, но выходные данные заметок могут быть получены из Sandcastle, а не из собственных тегов XML комментариев C#.
Вы можете попробовать использовать следующий код, где вы хотите поместить раздел заметок и посмотреть, что выводит Sandcastle (раньше это поддерживалось, не уверен, изменился ли он):
<alert class="note">This is a 'alert class=note'</alert>
См. Справку Longhorn для языка разметки Microsoft Assistance для получения дополнительной информации.