Цель использования тегов <value> и <summary> в документации Visual Studio XML

Question

Я работаю в C# в VS 2012, добавляя документацию XML в свой код, и я случайно включил правило StyleCop (в частности, SA1609), которое "проверяет, что открытое или защищенное свойство содержит заголовок документации с тегом значения ".

Есть также другое правило (SA1604, намеренно включенное на этот раз), которое "проверяет, что заголовок документации содержит правильно отформатированный итоговый тег".

Однако я изо всех сил пытаюсь увидеть, что вы поместите в тег значения, которого еще нет в теге итоговой суммы. В настоящее время мои итоговые теги говорят что-то вроде "Получает или устанавливает что-то". Что следует добавить в соответствующий тег значения, чтобы дополнить это?

(Просто чтобы уточнить, я доволен настройкой StyleCop - он просто привлек мое внимание к тегу значения, когда я случайно включил все правила документации)

MSDN не очень помогает с этим:

• Страница тега значения, по- видимому, подразумевает, что вы должны подробно указать, какое вспомогательное поле используется (что в любом случае кажется плохой идеей в интересах скрытия информации).
• Их документация с инструкциями по XML говорит, что "тег значения используется для описания значения свойства ". Я даже не уверен, что это значит - это звучит очень похоже на резюме для меня.

ТЛ; др

Какой смысл иметь теги сводки и значения в документации XML для свойств? Как их использовать, не повторяя себя?

Answer 1

Сводка должна дать общий обзор того, что может сделать свойство, тогда как значение описывает только то, какое значение ожидать от свойства.

Вот хороший пример различия на MSDN: List<T>.IList.IsFixedSize Property

Сводка: получает значение, указывающее, имеет ли IList фиксированный размер.

Значение: true, если IList имеет фиксированный размер; иначе ложно. В реализации по умолчанию List это свойство всегда возвращает false.

По большей части итоговые теги обычно указывают "Получает или задает значение...", тогда как теги значения обычно указывают, какие значения ожидать, включая ожидаемое значение по умолчанию.

Answer 2

Просто: это помогает поддерживать их актуальность по мере развития кода.

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