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

Question

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

• Встроенный метод 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 { ... }

Answer 1

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

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

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