Коментар Спадщина для C # (насправді будь-яка мова)

Припустимо, у мене є цей інтерфейс

public interface IFoo
{
    ///<summary>
    /// Foo method
    ///</summary>
    void Foo();

    ///<summary>
    /// Bar method
    ///</summary>
    void Bar();

    ///<summary>
    /// Situation normal
    ///</summary>
    void Snafu();
}

І цей клас

public class Foo : IFoo
{
    public void Foo() { ... }
    public void Bar() { ... }
    public void Snafu() { ... }
}

Чи є спосіб, чи є інструмент, який дозволяє мені автоматично поміщати коментарі кожного члена в базовий клас або інтерфейс?

Тому що я ненавиджу переписувати однакові коментарі для кожного похідного підкласу!

GhostDoc робить саме це. Для методів, які не успадковуються, він намагається створити опис з імені.

FlingThing() стає "Flings the Thing"

Ви завжди можете використовувати <inheritdoc />тег.

public class Foo : IFoo
{
    /// <inheritdoc />
    public void Foo() { ... }
    /// <inheritdoc />
    public void Bar() { ... }
    /// <inheritdoc />
    public void Snafu() { ... }
}

Використовуйте, /// <inheritdoc/>якщо хочете успадкування. Уникайте GhostDoc або чогось подібного.

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

Тим не менш, у нашій базі коду ми розміщуємо коментарі XML лише на інтерфейсах і додаємо додаткові коментарі до реалізації до класу. Це працює для нас, оскільки наші класи є приватними / внутрішніми, і лише інтерфейс є загальнодоступним. Кожного разу, коли ми використовуємо об'єкти через інтерфейси, ми маємо повне відображення коментарів у взаємодії.

GhostDoc - це хороший старт, який спростив процес написання коментарів. Особливо корисно постійно оновлювати коментарі, коли ви додаєте / видаляєте параметри, повторно запускаєте GhostDoc, і він оновить опис.

У Java це є, і я постійно ним користуюся. Просто зробіть:

/**
 * {@inheritDoc}
 */

І інструмент Javadoc це розгадує.

C # має подібний маркер:

<inheritDoc/>

Детальніше ви можете прочитати тут:

http://www.ewoodruff.us/shfbdocs/html/79897974-ffc9-4b84-91a5-e50c66a0221d.htm

Я б сказав, щоб безпосередньо використовувати

/// <inheritdoc cref="YourClass.YourMethod"/>  --> For methods inheritance

І

/// <inheritdoc cref="YourClass"/>  --> For directly class inheritance

Ви повинні розмістити цей коментар лише на попередньому рядку вашого класу / методу

Це отримає інформацію про ваші коментарі, наприклад, з інтерфейсу, який ви задокументували, наприклад:

    /// <summary>
    /// This method is awesome!
    /// </summary>
    /// <param name="awesomeParam">The awesome parameter of the month!.</param>
    /// <returns>A <see cref="AwesomeObject"/> that is also awesome...</returns>
    AwesomeObject CreateAwesome(WhateverObject awesomeParam);

Resharper має можливість копіювати коментарі з базового класу або інтерфейсу.

Інший спосіб - використовувати <see />тег документації XML. Це додаткові зусилля, але це працює нестандартно ...

Ось кілька прикладів:

/// <summary>
/// Implementation of <see cref="IFoo"/>.
/// </summary>
public class Foo : IFoo
{
    /// <summary>
    /// See <see cref="IFoo"/>.
    /// </summary>
    public void Foo() { ... }

    /// <summary>
    /// See <see cref="IFoo.Bar"/>
    /// </summary>
    public void Bar() { ... }

    /// <summary>
    /// This implementation of <see cref="IFoo.Snafu"/> uses the a caching algorithm for performance optimization.
    /// </summary>
    public void Snafu() { ... }
}

Оновлення:

Зараз я віддаю перевагу використанню, /// <inheritdoc/>яке зараз підтримується ReSharper.

У підсумку я створив інструмент для подальшої обробки файлів документації XML, щоб додати підтримку для заміни <inheritdoc/>тегу у самих файлах документації XML. Доступно за адресою www.inheritdoc.io (доступна безкоштовна версія).

Ну, є своєрідне власне рішення, яке я знайшов для .NET Core 2.2

Ідея полягає у використанні <include>тегу.

Ви можете додати <GenerateDocumentationFile>true</GenerateDocumentationFile>свій.csproj файл.

Ви можете мати інтерфейс:

namespace YourNamespace
{
    /// <summary>
    /// Represents interface for a type.
    /// </summary>
    public interface IType
    {
        /// <summary>
        /// Executes an action in read access mode.
        /// </summary>
        void ExecuteAction();
    }
}

І те, що успадковує від цього:

using System;

namespace YourNamespace
{
    /// <summary>
    /// A type inherited from <see cref="IType"/> interface.
    /// </summary>
    public class InheritedType : IType
    {
        /// <include file='bin\Release\netstandard2.0\YourNamespace.xml' path='doc/members/member[@name="M:YourNamespace.IType.ExecuteAction()"]/*'/>
        public void ExecuteAction() => Console.WriteLine("Action is executed.");
    }
}

Добре, це трохи страшно, але це додає очікувані елементи до YourNamespace.xml.

Якщо побудувати Debugконфігурацію, ви можете поміняти місцями Releaseдля Debugв fileатрибуті includeтега.

Для того, щоб знайти правильний member«S , nameщоб посилатися тільки відкритий згенерований Documentation.xmlфайл.

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

Яскравою стороною є те, що Visual Studio перевіряє скопійовані елементи, тому набагато простіше підтримувати синхронізацію документації та коду з інтерфейсом / базовим класом тощо (наприклад, імена аргументів, імена параметрів типу тощо).

У своєму проекті я закінчив роботу як <inheritdoc/>для DocFX, так і <include/>для публікації пакунків NuGet та перевірки на Visual Studio:

        /// <inheritdoc />
        /// <include file='bin\Release\netstandard2.0\Platform.Threading.xml' path='doc/members/member[@name="M:Platform.Threading.Synchronization.ISynchronization.ExecuteReadOperation(System.Action)"]/*'/>
        public void ExecuteReadOperation(Action action) => action();