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

Question

Предположим, у меня есть этот интерфейс

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() { ... }
}

Есть ли способ или есть инструмент, который позволяет мне автоматически добавлять комментарии каждого члена в базовый класс или интерфейс?

Потому что я ненавижу переписывать одни и те же комментарии для каждого производного подкласса!

Answer 1

Вы всегда можете использовать тег <inheritdoc />.

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

Answer 2

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

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

Answer 3

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

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

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

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

Answer 4

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

/**
 * {@inheritDoc}
 */

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

C # имеет похожий маркер:

<inheritDoc/>

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

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

Answer 5

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

Answer 6

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

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

Answer 7

Другой способ - использовать тег XML doc. Это дополнительное усилие, но оно работает "из коробки" ...

Вот несколько примеров:

    /// <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.

Answer 8

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