Как сделать исходный код частью документации XML и не нарушить DRY?
Rails.application.assets.logger = Logger.new(RUBY_PLATFORM =~ /(win|w)32$/ ? "NUL" : "/dev/null")
Rails::Rack::Logger.class_eval do
def call_with_quiet_assets(env)
previous_level = Rails.logger.level
Rails.logger.level = Logger::ERROR if env['PATH_INFO'].index("/assets/") == 0
call_without_quiet_assets(env).tap do
Rails.logger.level = previous_level
end
end
alias_method_chain :call, :quiet_assets
end
это тот же код, добавленный @choonkeat. Я просто включил работать под окнами.
4 ответа
Просто подбросить идею ...
Автоматизируйте процесс, который ищет блоки кода, каким-то образом разделенные, а затем вставьте этот код в комментарий 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
}
Я знаю, что это не красиво, но это начало! ;)
Для меня основная цель комментариев - описать код. копирование и вставка кода не приведет к достижению этой цели, поэтому я предполагаю, что мой вопрос может быть следующим: «Какова предполагаемая цель документации?» Вы хотите задокументировать, что метод делает с кем-то, вызывающим метод + (вроде как документация по API), или вы хотите, чтобы задокументировать, как работает метод, чтобы другой разработчик мог поддерживать исходный код? или что-то другое?
Если бы это первое, я бы вообще использовал код. Я бы сказал, что метод рассчитывает комиссию с учетом разных правил скидок и того, что включено в алгоритм. Бизнес-правила для этих вычислений не являются важной информацией в контексте API, они вполне могут измениться без изменения API (изменится только реализация интерфейса)
Если это вторая цель, повторение кода по-прежнему не будет соответствовать цели. Повторение чего-то делает его более ясным, повторение чего-то делает его более ясным, но пример того, как использовать метод, может помочь объяснить. Пример использования не будет повторением, и его нужно будет изменить только в случае изменения сигнатуры метода, а затем в любом случае потребуются изменения в документации
Вы можете поэкспериментировать с элементом include . Я никогда не использовал его, поэтому не знаю, можно ли смешивать этот элемент с другими, обычными элементами XML-комментария, но, судя по тому, как я читал (скудную) документацию, это не похоже.
Хотя это был бы лучший вариант, даже если это невозможно, вы могли бы объединить использование этого элемента со сценарием, который находит соответствующие фрагменты кода и вставляет их в файл XML.
Я бы, вероятно, хотя бы пойти другим путем. Поскольку выходные данные комментариев XML - это просто файл XML, вы можете обработать его после того, как он был создан, но перед запуском Sandcastle для него. Затем я бы сделал другой сценарий, который ищет весь код, который должен войти в файл справки, и извлекает его в отдельный файл XML.
Затем эти два XML-файла можно объединить с помощью XSLT и передать в SandCastle.
Как бы вы идентифицировали код, который должен войти в файл справки? В уме я могу придумать три варианта:
- Атрибуты
- Регионы
- Комментарии
Лично я бы предпочел Атрибуты.
В заключительном примечании я хотел бы указать из того, что, хотя это, безусловно, возможно, это, вероятно, больше работы, чем просто копирование и вставка и соблюдение некоторой дисциплины :)
Почему бы не воспользоваться более стандартным подходом к документированию кода с использованием полей типа
<summary>
<description>Displays Hello World!</description>
<arguments>None</arguments>
<returns>None</returns>
</summary>
Подумать только.