Создание документации в . NET / Хабрахабр. Качественная документация – неотъемлемая часть успешного программного продукта. Создание полного и понятного описания всех функций и возможностей программы и программного компонента требует немало сил и терпения. В данной статье я рассмотрю некоторые практические аспекты создания документации для .

Рациональной альтернативой представляется применение. Во-первых, в отличие от формата HTML, CHM является форматом с упаковкой. Первый из них платный, а все остальные относятся к категории freeware либо бесплатны для некоммерческого применения, что . Нашел применение как в NATO, так и в гражданских. Есть ли возможность генерировать CHM со всеми плюшками? После применения этого инструмента выделенный текстовый. Для файлов формата CHM и HLP здесь можно настроить набор.

CHM Editor это удобный WYSIWYG-редактор, который может быть использован для редактирования и перевода CHM файлов.

NET компонентов. Предположим, что у нас готова или почти готова некоторая . NET библиотека для разработчиков (они же конечные пользователи). API библиотеки безупречен, количество багов впечатляюще мало, да и вообще это не библиотека, а просто кладезь совершенного кода. Дело за малым – объяснить пользователям, как работать с этим замечательным продуктом. Есть разные подходы к написанию документации.

Некоторые команды предпочитают начинать создание документации в момент начала создания продукта. Другие откладывают написание мануалов на окончание работ. В некоторых командах документацию пишут специальные люди, которые ходят от разработчика к разработчику и от менеджера к менеджеру, аккумулируя знания о продукте. Во многих небольших командах таких специальных людей нет, а потому документацию часто пишет разработчик или разработчики. Кто- то использует сторонние средства вроде Help & Manual, в которых, как в заправском текстовом редакторе, можно создавать очень сложную верстку и на выходе получать документацию в многообразии форматов. Многие используют другой подход, широко пропагандируемый в последнее время – написание документации прямо в коде программы/библиотеки. Я в своей работе использовал и сторонние средства, и встроенные.

CHM Editor — портативный инструмент нового поколения, . После того, как xml-описание вашего компонента готово, можно сгенерировать. Приступаем к сборке документации в формате chm.

Начинал писать документацию и сразу, и в последний момент. В итоге я для себя решил, что документацию лучше начинать писать во второй половине создания продукта, так как чем ближе к завершению, тем более стабилен API, набор возможностей и т. Написание документации прямо в коде тоже, в конечном счете, оказалось удобнее, чем в сторонних программах, хотя поначалу казалось совсем наоборот.

Чтобы открыть в Windows CHM-файлы справки, полученные из Интернета, необходимо. Оформление Портфолио Старшеклассника Шаблоны. Программа DMDE 2.10 (DM Disk Editor and Data Recovery Software). GridinSoft CHM Editor: Лучший помощник. Ознакомьтесь с преимуществами CHM Editor и убедитесь, что этот .

Эта статья как раз о том, как писать документацию прямо в коде. Описываем API. Компиляторы C# и VB. NET умеют распознавать комментарии, оформленные специальным образом (xml комментарии) и при необходимости создавать xml файл, который можно потом использовать для создания документации.

Чтобы воспользоваться этой возможностью необходимо описать все публичные классы и методы с помощью xml комментариев. Выглядит это примерно так: /// < summary> /// Gets the R component from ABGR value returned by /// < see cref=. Его нужно включить в свойствах проекта на вкладке Build. В результате при компиляции, в дополнение к файлу вашей сборки, будет сгенерирован xml- файл, который содержит все xml- комментарии из кода (в том числе комментарии к непубличным структурам). Этот файл уже сам по себе полезен тем, что если его положить рядом со сборкой (вашей dll), то это позволит функции Intelli. Sense в Visual Studio отображать описания для методов в момент набора пользователем кода. Вот пример того, как это будет выглядеть для функции Get.

R, показанной выше: Однако в большинстве случаев сгенерированный xml- файл содержит комментарии к внутренним структурам, которые пользователям не нужно или нельзя видеть. Ниже я напишу, как автоматически очистить xml- файл так, чтобы в нем остались только описания к публичным методам. Я не буду подробно рассматривать все xml- теги, а лишь попробую кратко описать наиболее часто используемые. Тег summary служит для краткого описания назначения класса, интерфейса, перечисления (enum), методов и свойств класса или интерфейса и членов перечисления.

Тег param позволяет описать параметр, принимаемый функцией. Этот тег нужно использовать для каждого принимаемого параметра. Тег returns используется для описания возвращаемого значения функции. Тег value полезен для описания значения, которое принимает и/или возвращает некоторое свойство.

В некотором смысле тег value является аналогом тега returns./// < summary> /// Gets the font ascent./// < /summary> /// < value> The font ascent.< /value> /// < remarks> Ascent is the maximum height above the baseline reached/// by glyphs in this font, excluding the height of glyphs for/// accented characters.< /remarks> public short Ascent. Этот тег можно использовать практически везде кроме описания членов перечисления. На самом деле для членов перечисления тоже можно, но в документации, оформленной в стиле vs. Приведу еще несколько практических замечаний/рекомендаций.

Скачайте и установите расширение для Visual Studio под названием Ghost. Doc. Это расширение работает во всех версия студии (начиная с версии 2. По нажатию на Ctrl- Shift- D это расширение вставляет описание сущности, на которой в данный момент стоит курсор. Вставляются все необходимые теги, и генерируется текст описания на основе, например, названия метода и названия его параметров. Часто остается лишь откорректировать и дополнить сгенерированный текст.

Недостаток написания документации прямо в коде в том, что комментариев порой больше, чем кода, что может сильно затруднять чтение кода. Для обхода этой проблемы очень удобным оказывается полное разделение публичного интерфейса и реализации. Если у вас есть несколько перегруженных методов, то при генерации документации для них будет создана отдельная страница (вот пример такой страницы). Текст для этой страницы нужно указать в теге overloads в описании одного из перегруженных методов./// < summary> /// Saves the font bytes to the specified stream./// < /summary> /// < param name=.

Частичную спецификацию и отсутствующий префикс можно использовать, например, для ссылок между двумя методами одного класса или между двумя сущностями одного пространства имен (namespace). Пример использования частичной спецификации (Pdf. Font. Embed. Style находится в одном пространстве имен с Pdf. Font): public sealed class Pdf. Font. Примеры полной спецификации: ссылка на свойство< see cref=.

Можно сэкономить ручной труд, если копировать полные спецификации из ранее скомпилированного xml- файла. Со ссылками на группу перегруженных методов связана одна неприятность. Visual Studio требует, чтобы такие ссылки были вида O: XXX. YYY, в то время как Sandcastle Help File Builder требует, чтобы такие ссылки были вида Overload: XXX.

YYY. Для решения этой проблемы я использую простой скрипт, который вызывается на Post- build event и заменяет в xml- файле O: на Overload: , что вполне терпимо. Для ссылки на некоторую внешнюю статью вашей документации (не связанную с описанием API) или на некоторый ресурс в Интернет используйте старый добрый тег < a> с атрибутом href. Например, < a href = . В первом примере имя документа с внешней статьей представлено в форме “TOPIC. О том, что такое topic id, речь пойдет далее. Более глубоко ознакомиться с документированием кода с помощью xml комментариев можно в этих статьях: Генерируем файл документации. После того, как xml- описание вашего компонента готово, можно сгенерировать файл документации.

Я предпочитаю для этого использовать связку Sandcastle + Sandcastle Help File Builder (SHFB). Замечу, что некоторым больше по душе Doc. Project. Для этого требуется: Скачать и установить Sandcastlesandcastle. Скачать и установить Sandcastle Help File Buildershfb. Скачать и применить патч для стилей, используемых Sandcastlesandcastlestyles.

Если у вас возникнут проблемы со сборкой документации в формате HTML Help, то нужно проверить, что itircl. Обычно эта dll лежит в System. Подробнее написано тут: frogleg. Приступаем к сборке документации в формате chm. Для этого запускаем Sandcastle Help File Builder и настраиваем Project Properties.

В свойстве “Component. Configurations” можно настроить дополнительные компоненты, используемые при сборке. Если вы не знаете, какие компоненты вам могут быть нужны, то можно выбрать все компоненты. В любом случае я рекомендую всегда использовать Intelli. Sense Component, так как он автоматически создает копию входного xml- файла, очищенную от всех непубличных комментариев.