Как сделать исходный код частью XML-документации и не нарушать DRY? - PullRequest
Новая
       39

Как сделать исходный код частью XML-документации и не нарушать DRY?

6 голосов
/ 24 июня 2009

Я хотел бы добавить части исходного кода в документацию XML. Я мог бы скопировать и вставить исходный код в elements, like this:</p> <pre><code>/// <summary> /// Says hello world in a very basic way: /// <code> /// System.Console.WriteLine("Hello World!"); /// System.Console.WriteLine("Press any key to exit."); /// System.Console.ReadKey(); /// /// статическая пустота Main () { System.Console.WriteLine («Привет, мир!»); System.Console.WriteLine («Нажмите любую клавишу для выхода.»); System.Console.ReadKey (); }

Поддерживать это будет больно. Существуют ли другие возможности для добавления исходного кода в документацию XML в C #?

Я обрабатываю документацию XML с помощью Sandcastle и хотел бы сделать из нее файл технической помощи (* .chm). Я хотел бы добавить части или полные тела метода в этот файл справки.

EDIT: Спасибо за комментарий от slide_rule. Я добавил более реалистичный и менее тривиальный пример:

Предположим, у меня есть такой метод: 

public decimal CalculateFee(Bill bill)
{
    if (bill.TotalSum < 5000) return 500;
    else
    {
        if (bill.ContainsSpecialOffer) return bill.TotalSum * 0.01;
        else return bill.TotalSum * 0.02;
    }
}

Было бы неплохо иметь возможность добавить информацию о том, как плата рассчитывается в файл технической помощи.

Наиболее очевидным решением было бы записать алгоритм в виде прозаического текста в комментарии, например: «Если общая сумма счета меньше 5000, то ...».

Другим решением было бы скопировать и вставить тело метода в поле комментария и поместить его в элемент . Тело этого метода можно понять довольно легко, даже без особых знаний о C #, поэтому нет ничего плохого в том, чтобы поместить его в файл технической помощи.

Оба решения нарушают принцип DRY! Я хотел бы добавить тела метода или части тела метода в файл справки, не дублируя информацию.

Возможно ли это в C #? (Я думаю, что RDoc для Ruby способен сделать это, но мне нужно какое-то решение в C #)

Ответы [ 4 ]

1 голос
/ 25 июня 2009

Почему бы не перейти к более стандартному подходу для документирования кода с помощью полей типа 

<summary>
   <description>Displays Hello World!</description>
   <arguments>None</arguments>
   <returns>None</returns>
</summary>

Просто мысль.

1 голос
/ 25 июня 2009

Для меня главная цель комментариев - описать код. копирование и вставка кода не будут полностью соответствовать этой цели, поэтому я предполагаю, что мой вопрос может быть «Какова цель документации?» Желаете ли вы документировать, что метод делает с кем-то, вызывающим метод + (вроде документации API), или вам нужно документировать, как метод работает, чтобы другой разработчик мог поддерживать исходный код? или что-то другое?

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

Если вторая цель повторяется, код все равно не выполнит цель. Повторение чего-либо делает его более понятным, повторение чего-либо делает его более понятным, но пример того, как использовать метод, может помочь объяснить. Пример использования не будет повторением, и его нужно будет изменить только в том случае, если сигнатура метода изменится, а затем в любом случае потребуются изменения в документации

1 голос
/ 25 июня 2009

Просто подбрасываю идею ...

Автоматизируйте процесс, который ищет блоки кода, разделенные каким-либо образом, а затем вставьте этот код в комментарий XML. 

/// <summary>
/// Says hello world in a very basic way:
/// <code>
///     Code block 1
/// </code>
/// </summary>
static void Main() 
{
    // Code block 1 start
    System.Console.WriteLine("Hello World!");
    System.Console.WriteLine("Press any key to exit.");
    System.Console.ReadKey();
    // Code block 1 end
}

Я знаю, что это не красиво, но это начало! ;)

0 голосов
/ 25 июня 2009

Вы можете поиграть с включенным элементом . Я никогда не использовал его, поэтому я не знаю, можно ли смешивать этот элемент с другими, обычными элементами XML Comment, но то, как я читаю (разреженную) документацию, выглядит не так.

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

Я бы, наверное, пошел другим путем. Поскольку вывод XML Comments представляет собой просто XML-файл, вы можете обработать его после того, как он был создан, но до запуска Sandcastle. Затем я сделал бы другой сценарий, который ищет весь код, который нужно ввести в файл справки, и извлек его в отдельный файл XML.

Эти два XML-файла затем можно объединить с помощью XSLT и передать в SandCastle.

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

  • Атрибуты
  • Регионы
  • Комментарии

Лично я бы предпочел Атрибуты.

В заключительной заметке я хотел бы отметить, что, хотя это, безусловно, возможно, это, вероятно, больше, чем просто копирование, вставка и соблюдение дисциплины:)

...