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 .
- A wallchart , сопровождающий мою статью о Simple-Talk.com под названием Укрощение Sandcastle: руководство программиста .NET для документирования кода . Обратите внимание, что в статье есть ссылка, чтобы добраться до настенной диаграммы, но она находится в самом низу статьи, поэтому я дал ссылки для обоих здесь. (У меня также есть ссылка на руководство Dyncity в моей статье; я свяжусь с редакцией, чтобы узнать, хотят ли они разместить локальную копию теперь осиротевшего руководства Dyncity и опубликовать обновление здесь, если они это сделают.)
Здесь речь идет обо всех документация существует для элемента
<note>. (Это из моей настенной диаграммы; руководство Dyncity говорит по существу то же самое, но гораздо менее сжато.)
Эта неадекватная документация, к сожалению, все, что я нашел о
<note>. Поэтому я провел быструю пробную версию, вложив каждый тип заметки в раздел Примечания. Вот что он произвел:
То есть с помощью
type="caution"Вы получаете значок предупреждения и метку, в то время как другие два атрибута типа значения произвели тот же значок заметки и метку в моем конкретном примере. Я подозреваю, что есть и другие аспекты его использования, глубоко скрытые в подлеске.
Чтобы расширить комментарий cubrr к ответу Бобби, на самом деле теперь есть довольно обширная документация по элементу Note в Sandcastle.
Существует четыре категории примечаний,которые можно добавить к любому другому элементу xml по умолчанию, например к элементам remark или summary. Они носят общий, предостерегающий, охранительный или языковой характер. Главным различием между ними, по-видимому, является тип значка, который они дают заметке, и название, которое она имеет рядом со значком. Вы можете увидеть полный список всех эти типы заметок здесь .
Следующий код сгенерировал для меня следующий результат:
/// <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>Смотрите: Microsoft Assistance Markup Language Longhorn Help для получения дополнительной информации.