Способы синхронизировать интерфейс и реализацию комментируют в [закрытом] C#

Question

Способы синхронизировать интерфейс и реализацию комментируют в [закрытом] C#

Вот способ сделать это смутно, основываясь на этом ответе:

function weightedIntegerValues(weights, total) {
    let flooredValues = [];
    const weightSum = weights.reduce((sum, item) => {
        return sum + valueFunc(item);
    }, 0);

    let flooredSum = 0

    weights.forEach((weight, i) => {
        const weighted = total * weight / weightSum
        const floored = Math.floor(weighted);

        flooredValues.push({
            floored: floored,
            diff: weighted - floored,
            index: i
        });

        flooredSum = flooredSum + flooredValues[i].floored;
    });

    flooredValues = flooredValues.sort((a, b) => b.diff - a.diff);

    const difference = total - flooredSum;

    for (let i = 0; i < difference; i++) {
        flooredValues[i].floored += 1;
    }

    return flooredValues.sort((a, b) => a.index - b.index).map(v => v.floored);
}

92

c# documentation xml-documentation

задан Valentin 5 May 2009 в 09:37

8 ответов

Если вы его еще не используете, я настоятельно рекомендую бесплатное дополнение Visual Studio под названием GhostDoc . Это облегчает процесс документации. Взгляните на мой комментарий по несколько схожему вопросу.

Хотя GhostDoc не будет выполнять синхронизацию автоматически, он может помочь вам в следующем сценарии:

У вас есть документированный метод интерфейса. Реализуйте этот интерфейс в классе, нажмите сочетание клавиш GhostDoc, Ctrl-Shift-D , и XML-комментарий из интерфейса будет добавлен к реализованному методу.

Перейдите к Опции -> Настройки клавиатуры и назначить ключ для GhostDoc.AddIn.RebuildDocumentation (я использовал Ctrl-Shift-Alt-D ).

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

12

ответ дан 24 November 2019 в 06:35

I usually write comments like this:

/// <summary>
/// Implements <see cref="IMyInterface.Foo(string, int)"/>
/// </summary>
/// <returns></returns>

The methods are used only by the interface, so this comment is not even shown in tooltips when coding.

Edit:

If you want to see docs when you call the class directly and not using the interface, you need to write it twice or use a tool like GhostDoc.

5

ответ дан 24 November 2019 в 06:35

Попробуйте GhostDoc ! Это работает для меня: -)

Редактировать: Теперь, когда мне стало известно о поддержке Сандкаслом , я поддерживаю пост Нолдорина. Это гораздо лучшее решение. Тем не менее, я все еще рекомендую GhostDoc на общих основаниях.

4

ответ дан 24 November 2019 в 06:35

/// <inheritDoc/>

Читайте здесь

Используйте это

1

ответ дан 24 November 2019 в 06:35

Don't do that. Think of it this way - if both comments are required to be the same all the time, then one of them isn't necessary. There has to be a reason for the comment (besides some kind of weird obligation to comment-block every function and variable) so you need to figure out what that unique reason is and document that.

0

ответ дан 24 November 2019 в 06:35

С помощью ReSharper вы можете скопировать его, но я не думаю, что он синхронизируется постоянно.

0

ответ дан 24 November 2019 в 06:35

I have a better answer: FiXml., I'm one of its authors

Cloning the is certainly working approach, but it has significant disadvantages, e.g.:

When the original comment is changed (which frequently happens during development), its clone is not.
You're producing huge amount of duplicates. If you're using any source code analysis tools (e.g. Duplicate Finder in Team City), it will find mainly your comments.

As it was mentioned, there is tag in Sandcastle, but it has few disadvantages in comparison to FiXml:

Sandcastle produces compiled HTML help files - normally it does not modify .xml files containing extracted XML comments (at last, this can't be done "on the fly" during the compilation).
Sandcastle's implementation is less powerful. E.g. the is no .

See Sandcastle's description for further details.

Short description of FiXml: it is a post-processor of XML documentation produced by C# \ Visual Basic .Net. It is implemented as MSBuild task, so it's quite easy to integrate it to any project. It addresses few annoying cases related to writing XML documentation in these languages:

No support for inheriting the documentation from base class or interface. I.e. a documentation for any overridden member should be written from scratch, although normally it’s quite desirable to inherit at least the part of it.
No support for insertion of commonly used documentation templates, such as “This type is singleton - use its property to get the only instance of it.”, or even “Initializes a new instance of class.”

To solve mentioned issues, the following additional XML tags are provided:

, tags
attribute in tag.

Here is its web page and download page.

2

ответ дан 24 November 2019 в 06:35

Другие вопросы по тегам:

c# documentation xml-documentation

Похожие вопросы:

score 59 · Accepted Answer

Вы можете сделать это довольно легко, используя тег Microsoft Sandcastle (или NDoc) inheritdoc . Это официально не поддерживается спецификацией, но пользовательские теги вполне приемлемы, и действительно Microsoft решила скопировать этот (и один или два других тега) из NDoc при создании Sandcastle.

/// <inheritdoc/>
/// <remarks>
/// You can still specify all the normal XML tags here, and they will
/// overwrite inherited ones accordingly.
/// </remarks>
public void MethodImplementingInterfaceMethod(string foo, int bar)
{
    //
}

Здесь находится страница справки из Графический интерфейс справочного файла Sandcastle, в котором полностью описывается его использование.

(Конечно, это не просто «синхронизация», как упоминается в вашем вопросе, но, тем не менее, это именно то, что вы ищете.)

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

Изменить: Что касается вашего обновления, Sandcastle также может позаботиться об этом для вас. Sandcastle может вывести измененную версию фактического XML-файла, который он использует для ввода, что означает, что вы можете распространять эту модифицированную версию вместе с библиотекой DLL вместо той, которая создается непосредственно Visual Studio, что означает, что у вас есть комментарии в intellisense, а также файл документации (CHM, что угодно).

Что касается вашего обновления, Sandcastle также может позаботиться об этом за вас. Sandcastle может вывести измененную версию фактического XML-файла, который он использует для ввода, что означает, что вы можете распространять эту модифицированную версию вместе с библиотекой DLL вместо той, которая создается непосредственно Visual Studio, что означает, что у вас есть комментарии в intellisense, а также файл документации (CHM, что угодно).