Самый простой способ добавить XML документ в проект WinRT

У нас есть группа разработчиков, которая переходит с C++ на C# и WinRT. Мы использовали D'Oxygen в качестве части наших сборок для разработчиков на C++, и я хотел бы продолжить создание документов в рамках сборки для разработчиков на C#/WinRT.

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

Похоже, NDoc теперь не работает, и я быстро взглянул на Sandcastle, но нашел его довольно сложным. В идеале, я ищу что-то, что не слишком обременяет разработчиков или требует от них запоминать дополнительные шаги при редактировании, сборке, тестировании и фиксации. Другими словами, лучшим решением было бы то, что "просто происходит", например, шаг после сборки, и не вносит значительный вклад во время сборки каждого разработчика.

Если у кого-то есть опыт работы с C#/WinRT, я бы обязательно посоветовался.

Заранее спасибо!

Источник

2 ответа

Решение
  1. Получить Sandcastle Help File Builder.
  2. Создайте проект справки для своей библиотеки в решении Visual Studio.
  3. Снимите флажок Build из конфигурации решения Debug, чтобы построить проект документации только в конфигурациях Release, поскольку Debug чаще всего используется во время разработки. Для тестирования сборки выпуска или тестирования производительности вы можете либо создать другую конфигурацию решения, либо просто переключить опцию вперед и назад.
  4. Создайте документацию один раз
  5. Включите файл документации в решение, чтобы оно отображалось в окне "Ожидающие изменения" при изменении файла.
  6. Пожалуйста, попросите ваших разработчиков создать конфигурацию выпуска, которая обновляет документацию перед регистрацией, или используйте любую другую политику, чтобы потребовать обновления документации.

Запуск Configuration ManagerДиспетчер конфигурации с документацией Отключение сборки для конфигурации отладкиСтруктура решения, облегчающая просмотр и проверку обновлений файла.chm

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

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

РЕДАКТИРОВАТЬ*

Sandcastle предоставляет различные форматы вывода, как показано в свойствах проекта:

Источник

Я хотел бы упомянуть ForgeDoc (из которых я разработчик), это может быть то, что вы ищете. Он разработан, чтобы быть быстрым и простым, и он генерирует правильный вывод HTML-подобный MSDN. Он также имеет интерфейс командной строки, так что вы можете просто вызвать его из команды события после сборки в Visual Studio.

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

Источник
Другие вопросы по тегам