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

Question

Это вовсе не важная персона, но что-то действительно очень полезное, если ее решить.

Когда я перегружаю методы и т. Д., Бывают случаи, когда xml-комментарии в точности совпадают, имена параметров в столбце 1 или 2. Я должен скопировать / вставить комментарии к каждому перегруженному методу, где они одинаковы. Однако иногда это может привести к вводящей в заблуждение информации о методе, если я обновлю один из них и забуду вернуться и скопировать / вставить его для всех остальных. Если существует много перегруженных методов, это может занять много времени и привести к ошибке.

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

Вот пример:

    /// <summary>
    /// Go and do something
    /// </summary>
    public void DoSomething()
    {
        DoSomething(true, "Done something");
    }

    /// <summary>
    /// Go and do something
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    public void DoSomething(bool doIt)
    {
        DoSomething(doIt, "Done something");
    }

    /// <summary>
    /// Go and do something cool
    /// </summary>
    /// <param name="doIt">whether it should be done or not</param>
    /// <param name="doneMessage">message to show once done</param>
    public void DoSomething(bool doIt, string doneMessage)
    {
        if (doIt)
            Console.WriteLine(doneMessage);
    }

Итак, как вы видите, все комментарии одинаковы, за исключением того, что я решил внести поправку в последний комментарий: «Иди и сделай что-нибудь классное». Теперь я должен пойти и изменить это все остальные комментарии метода тоже.

Приветствие.

Answer 1

Согласно этим спецификациям:

http://msdn.microsoft.com/en-us/library/5ast78ax.aspx

Не существует установленного стандарта для комментариев XML; те, что показаны на этой странице, просто «рекомендуются». В рекомендуемых тегах такой функции нет. Однако инструмент документации XML с радостью принимает следующее без предупреждения:

/// <summary id="30">foo</summary>
void bar();

/// <summary id="30"/>
void bar(int baz);

Будет ли это полезно для вас или нет, зависит от того, что именно вы делаете с файлом XML, который выдает компилятор. К сожалению, такие вещи, как Intellisense (завершение кода, всплывающие подсказки в IDE и т. Д.). ничего с этим не сделаю.

РЕДАКТИРОВАТЬ: Попробуйте <include>, как описано в http://msdn.microsoft.com/en-us/library/9h8dy30z.aspx. Это немного тяжеловесно, потому что для этого требуется отдельный файл, но если ваша документация огромна, это может стоить этого.

Answer 2

В стандартных тегах комментариев XML такой функции нет. Построитель файлов справки Sandcastle , с другой стороны, реализует <наследственный_док /> , который вы ищете.

Answer 3

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

interface ISomeInterface
{
    /// <summary>Handles this and that.</summary>
    void SomeMethod();

    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    /// <param name="i">Param blabla.</param>
    void SomeMethod(int i);
}

class SomeClass : ISomeInterface
{
    /// <summary><see cref="ISomeInterface.SomeMethod()"/></summary>
    public void SomeMethod() { }

    /// <summary><see cref="ISomeInterface.SomeMethod(int)"/></summary>
    public void SomeMethod(int i) { }
}

Answer 4

Называйте меня глупо, но поиск по документу и замена для Go and do something в сочетании с добросовестным использованием Alt + R или Alt + A может сделать это спорным.Одно редактирование - ну, набирается хотя бы один раз.

@ Ответы Рейндериена информативны ... но не очень полезны, если целью является использование IntelliSense или стандартного инструмента обработки.он также информативен и круче, я думаю, что он обращается к SHFB для обработки ... но все еще не IntelliSense.

@ Paw Baltzersen ответ может быть использован независимо от использования интерфейса и заманчиво ... но не делаетПравильно получите IntelliSense.

Мне нравится избегать поиска и замены там, где это возможно, но получение IntelliSense здесь, как правило, будет моей первой заботой.