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

Question

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

}

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

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

762 8

inheritance c#comments

8 ответов:

Comments

Ничего не найдено.

James Curran · Accepted Answer · 2008-12-05 07:15:00

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

FlingThing () становится "бросает вещь"

Vadim · Accepted Answer · 2011-09-27 18:22:10

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

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

JeffHeaton · Accepted Answer · 2012-07-04 14:38:49

в Java, и я использую его все время. Просто сделайте:
/**
 * {@inheritDoc}
 */
и инструмент Javadoc выясняет это.

C# имеет аналогичный маркер:
<inheritDoc/>
Вы можете прочитать здесь:

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

svick · Accepted Answer · 2011-04-21 20:16:32

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

Dennis · Accepted Answer · 2018-04-19 14:53:28

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

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

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

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

Mathias Rotter · Accepted Answer · 2017-09-21 12:13:49

другой способ-использовать тег 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.

K Johnson · Accepted Answer · 2017-12-20 08:31:42

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

gatsby · Accepted Answer · 2018-09-19 09:33:49

Я бы сказал напрямую использовать
/// <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);