Наследование комментариев для C# (на самом деле любой язык)

GhostDoc делает именно это. Для методов, которые не унаследованы, он пытается создать описание на основе имени.

FlingThing() становится "Flings the Thing"

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

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

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

GhostDoc - хорошее начало, он упростил процесс написания комментариев. Особенно полезно поддерживать комментарии в актуальном состоянии, когда вы добавляете / удаляете параметры, повторно запускаете GhostDoc и он обновляет описание.

Это есть в Java, и я постоянно им пользуюсь. Просто сделать:

/**
 * {@inheritDoc}
 */

И инструмент Javadoc это понимает.

В C# есть аналогичный маркер:

<inheritDoc/>

Вы можете прочитать больше здесь:

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

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

Вы всегда можете использовать тег <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
}

Другой способ - использовать тег документации <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 (доступна бесплатная версия).

Я бы сказал, чтобы напрямую использовать

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

Что ж, есть какое-то родное решение, которое я нашел для .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.

Чтобы найти правильный membername для ссылки, просто откройте сгенерированный файл 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();