XML Комментирование частичных классов/методов

Существует ли стандартный способ, с помощью которого инструменты, используемые для создания документов API, обрабатывают комментарии XML Style для частичных классов? В принципе, как следует комментировать частичный класс/метод, чтобы полученные документы справки не искажались? Этот вопрос может меняться в зависимости от используемого инструмента, и в этом случае я думаю, что два наиболее важных из них:

  • Visual Studio встроенный метод для создания документации XML
  • Microsoft Sandcastle

Я не хочу, чтобы моя документация XML выходила на фанк, это все

/// <summary>Some Foo class</summary>
public partial class Foo { ... }

/// <summary>Some Foo class that implements some interface.</summary>
public partial class Foo : ISomeInterface { ... }

Ответы

Ответ 1

Лучшей практикой является предоставление XML-комментариев только одному из частных определений. Не должно быть необходимости разделять публичные комментарии для 1 класса на 2 места.

Как работает Visual Studio, один комментарий будет переопределять другой. (Вы можете подтвердить это, создав 2 частичных определения одного и того же класса с разными комментариями XML, затем создайте переменную этого типа. Intellisense покажет только 1 из комментариев XML.)

Это также будет поведение любого инструмента документации, использующего XML файл комментариев, созданный Visual Studio, который включает в себя Sandcastle.