Способи синхронізації інтерфейсу та коментарів до реалізації в C # [закрито]

Чи існують автоматичні способи синхронізації коментарів між інтерфейсом та його реалізацією? Зараз я документую їх обох і не хотів би синхронізувати їх вручну.

ОНОВЛЕННЯ:

Розглянемо цей код:

interface IFoo{
    /// <summary>
    /// Commenting DoThis method
    /// </summary>
    void DoThis();
}
class Foo : IFoo {
    public void DoThis();
}

Коли я створюю такий клас:

IFoo foo=new Foo();
foo.DoThis();//comments are shown in intellisense

Тут коментарі не відображаються:

Foo foo=new Foo();
foo.DoThis();//comments are not shown in intellisense

<inheritDoc/>Тег буде відмінно генерувати документацію в замку Sand, але він не працює в IntelliSense підказках.

Будь ласка, поділіться своїми ідеями.

Дякую.

Ви можете зробити це досить легко, використовуючи inheritdocтег Microsoft Sandcastle (або NDoc) . Це офіційно не підтримується специфікацією, але власні теги цілком прийнятні, і справді Microsoft вирішила скопіювати цей (і один або два інших теги) з NDoc, коли вони створювали Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Ось сторінка довідки з графічного інтерфейсу конструктора файлів довідки Sandcastle, де повністю описано його використання.

(Звичайно, це не конкретно "синхронізація", як згадується у вашому запитанні, але, здається, це саме те, що ви шукаєте.)

Як примітка, це для мене звучить цілком справедливою ідеєю, хоча я зауважив, що деякі люди вважають, що ви завжди повинні поважати коментарі в похідних та реалізованих класах. (Я насправді робив це сам, документуючи одну зі своїх бібліотек, і я не бачив жодних проблем.) Майже завжди немає причин, щоб коментарі взагалі відрізнялись, то чому б просто не успадкувати та зробити це простим способом?

Редагувати: Щодо вашого оновлення, Sandcastle також може подбати про це. Sandcastle може вивести модифіковану версію власне XML-файлу, який він використовує для введення, що означає, що ви можете розповсюджувати цю модифіковану версію разом із бібліотекою DLL замість тієї, яку створив безпосередньо Visual Studio, а це означає, що у вас є коментарі в intellisense, а також файл документації (CHM, що завгодно).

Якщо ви вже не використовуєте його, я настійно рекомендую безкоштовний аддон Visual Studio під назвою GhostDoc . Це полегшує процес документування. Погляньте на мій коментар до дещо пов’язаного питання.

Хоча GhostDoc не виконує синхронізацію автоматично, це може допомогти вам у наступному сценарії:

У вас є задокументований метод інтерфейсу. Впровадьте цей інтерфейс у клас, натисніть ярлик GhostDoc Ctrl-Shift-D, і коментар XML з інтерфейсу буде доданий до реалізованого методу.

Перейдіть до Параметри -> Налаштування клавіатури та призначте клавішу GhostDoc.AddIn.RebuildDocumentation(я використовував Ctrl-Shift-Alt-D).

Тепер, якщо ви змінили коментар XML на інтерфейсі , просто натисніть цю комбінацію клавіш на реалізованому методі, і документація буде оновлена. На жаль, це не працює навпаки.

Я зазвичай пишу такі коментарі:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

Методи використовуються лише інтерфейсом, тому цей коментар навіть не відображається в підказках під час кодування.

Редагувати:

Якщо ви хочете бачити документи, коли ви безпосередньо викликаєте клас і не використовуєте інтерфейс, вам потрібно написати його двічі або скористатися таким інструментом, як GhostDoc.

Спробуйте GhostDoc ! У мене це працює :-)

Редагувати: Тепер, коли мені стало відомо про підтримку Sandcastle <inheritdoc/>, я схвалюю пост Нолдоріна. Це набагато краще рішення. Однак я все-таки рекомендую GhostDoc на загальних підставах.

У мене є краща відповідь: FiXml . , Я є одним з його авторів

Клонування - це, безумовно, робочий підхід, але він має суттєві недоліки, наприклад:

• Коли оригінальний коментар змінюється (що часто трапляється під час розробки), його клон не є.
• Ви виробляєте величезну кількість дублікатів. Якщо ви використовуєте будь-які засоби аналізу вихідного коду (наприклад, Duplicate Finder у Team City), він знайде в основному ваші коментарі.

Як було згадано, <inheritdoc>тег у Sandcastle є , але він має кілька недоліків у порівнянні з FiXml:

• Sandcastle створює скомпільовані файли довідки HTML - зазвичай він не модифікує .xmlфайли, що містять витягнуті коментарі XML (нарешті, цього не можна зробити "на льоту" під час компіляції).
• Впровадження Sandcastle є менш потужним. Наприклад, ні <see ... copy="true" />.

Докладнішу інформацію див. В <inheritdoc>описі Sandcastle .

Короткий опис FiXml: це постпроцесор XML-документації, вироблений C # \ Visual Basic .Net. Він реалізований як завдання MSBuild, тому його досить просто інтегрувати до будь-якого проекту. У ньому розглядається кілька прикрих випадків, пов’язаних із написанням документації XML цими мовами:

• Немає підтримки для успадкування документації від базового класу або інтерфейсу. Тобто документація для будь-якого перезаписаного члена повинна бути написана з нуля, хоча зазвичай цілком бажано успадкувати принаймні її частину.
• Немає підтримки для вставки загальновживаних шаблонів документації , таких як „Цей тип є одностороннім - використовуйте його <see cref="Instance" />властивість, щоб отримати єдиний його екземпляр.“, Або навіть „Ініціалізує новий екземпляр <CurrentType>класу“.

Для вирішення згаданих проблем надаються такі додаткові теги XML:

• <inheritdoc />, <inherited /> теги
• <see cref="..." copy="..." />атрибут у <see/>тезі.

Ось його веб-сторінка та сторінка завантаження .

/// <inheritDoc/>

Прочитайте тут

Використовуй це

Я створив бібліотеку для подальшої обробки файлів документації XML, щоб додати підтримку тегу <nasleditdoc />.

Незважаючи на те, що це не допомагає з Intellisense у вихідному коді, воно дозволяє включити модифіковані файли документації XML до пакета NuGet і, отже, працює з Intellisense у посиланих пакетах NuGet.

Більше інформації на www.inheritdoc.io (доступна безкоштовна версія).

Не роби цього. Подумайте про це так - якщо обидва коментарі повинні бути постійно однаковими, то один із них не потрібен. Для коментаря повинна бути причина (крім якогось дивного зобов’язання блокувати коментарі кожну функцію та змінну), тому вам потрібно з’ясувати, що це за унікальна причина, і задокументувати це.

За допомогою ReSharper ви можете скопіювати його, але я не думаю, що він постійно синхронізується.