Описание Атрибут против <summary>тег для свойств - PullRequest
4 голосов
/ 04 апреля 2011

Я пишу библиотеку классов на C # в соответствии с VS 2005 (я знаю, с современностью, но у нас ограниченный бюджет).

Мне кажется, что если я использую«Сводка» в документации XML, мои пользователи могут видеть эту информацию через Intellisense, всплывающие подсказки и т. д., но не в окне «Свойства» в Studio.

Чтобы получить что-то в этом окне, мне кажется, чтоиспользуйте атрибут [Description("This is it")].

Я прав?Если это так, то может показаться, что мне нужно продублировать описание :-(

Или есть способ получше? Спасибо!

Ответы [ 3 ]

7 голосов
/ 04 апреля 2011

Да, это правильно.Два метода имеют совершенно разные цели.

  • Комментарии /// <summary></summary> используются для генерации XML-документации для вашего проекта во время компиляции, которая также анализируется Visual Studio для ее базы данных IntelliSense..

  • [DescriptionAttribute] предоставляет текст описания, который используется в конструкторе, особенно в нижней части окна свойств.

Microsoftсобственная библиотека Windows Forms изобилует обоими этими.

Я не знаю ни одного способа слияния двух, но подумайте, действительно ли вы хотите, чтобы они были точно одинаковыми.В моих собственных библиотеках классов я часто хочу отображать в конструкторе немного другую информацию, чем я хочу включить в свою техническую документацию.

В качестве простого примера, я мог бы захотеть прояснить в конструкторе, что это свойствоне поддерживается в определенных версиях Windows, но перенесите эту информацию в раздел <remarks> в моих технических документах:

/// <summary>
/// Gets or sets a value indicating whether a shield should be displayed
/// on this control to indicate that process elevation is required.
/// </summary>
/// <remarks>
/// The elevation-required shield is only supported under Windows Vista
/// and later. The value of this property will be ignored under earlier
/// operating systems.
/// </remarks>
[Category("Appearance")]
[Description("Displays a shield to indicate that elevation is required. " +
             "(Only applies under Windows Vista and later.)")]
public bool ShowShield { get; set; }
2 голосов
/ 04 апреля 2011

Итоговый XML-тег документа и атрибут Description являются двумя совершенно разными вещами .

Сводный тег предназначен для использования в ДОКУМЕНТАЦИИ для компонента.

Атрибут Description является частью модели компонента contols и доступен в приложении в во время выполнения . Это означает, что информация компилируется в ваш двоичный файл сборки. Потенциально содержимое атрибута описания даже видно конечным пользователям вашего приложения (например, при использовании элемента управления PropertyGrid).

Если вы ищете документацию, используйте только документ XML. Если вы хотите создать повторно используемый компонент, вы также можете использовать атрибут Description.

0 голосов
/ 04 апреля 2011

Насколько я понимаю, вы правы. Тем не менее, вы можете автоматизировать большую часть этой работы , используя GhostDoc , у которого есть бесплатная версия, которую вы можете настроить для добавления в свой атрибут Description.

...