Наследование комментариев для 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() { ... }
}

Используя crefатрибут, вы даже можете ссылаться на совершенно другой член в совершенно другом классе или пространстве имен!

public class Foo
{
    /// <inheritdoc cref="System.String.IndexOf" />
    public void Bar() { ... } // this method will now have the documentation of System.String.IndexOf
}

Используйте, /// <inheritdoc/>если хотите наследование. Избегайте GhostDoc или чего-то подобного.

Согласен, раздражает, что комментарии не передаются по наследству. Было бы довольно просто создать надстройку, если бы у кого-то было время (я бы хотел).

Тем не менее, в нашей базе кода мы помещаем XML-комментарии только к интерфейсам и добавляем дополнительные комментарии реализации к классу. Это работает для нас, поскольку наши классы являются частными / внутренними и только интерфейс является общедоступным. Каждый раз, когда мы используем объекты через интерфейсы, у нас есть полные комментарии, отображаемые в intellisence.

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();