Генерация справочной системы для .net-библиотек или .net-приложений

Никогда не нужно лениться писать подробные (в меру) комментарии в исходном коде своих программ:

• Во первых - по прохождении некоторого времени не всегда сразу вспоминаешь что именно делает тот или иной код (комментарии помогут в этом быстро разобраться). 
• Во вторых - на основе комментариев можно быстро сгенерировать подробную справочную систему, подобную той, что имеется в MSDN или в др. широко известных ресурсах. Чем более подробными будут комментарии (с примерами, объяснениями), тем более качественной получится справочная система.

Примечание

В свойствах проекта MS Visual Studio 2010 на вкладке Построение должна быть установлена галочка XML-файл документации. По умолчанию в текстовом поле, возле обозначенной галочки, будет задан нужный путь к результирующему xml-файлу. Этот файл должен иметь такое же имя как и результирующий файл сборки и размещаться в том же каталоге.

Для генерации справочной системы существуют различные программные продукты. Изначально я думал воспользоваться программой Doc-oMatic, однако с ней у меня возникали серьёзные проблемы. Коротко расскажу о них.

Doc-o-Matic 7

Я скачал для использования две версии продукта: Express и Professional. Результат их работы для меня оказался несколько неожиданным. Кратко опишу свои впечатления об обоих версиях.

Doc-o-Matic 7 Express

В формате html документация генерируется неплохо. Есть некоторые неприятные моменты, касающиеся навигации в сгенерированной справочной системе, но главное, что всё читается. 

Формат справки windows и справки формата MS Visual Studio оказался не рабочим - в самом конце, при сборке справки 100% вылезают ошибки. Тестировал на Windows XP SP3 x86 Rus, а так же на Windows 7 SP1 x64 Rus. На машинах установлены SDK для MS Visual Studio 2008/2010, а так же сама MS Visual Studio 2010 SP1 Premium Rus. 

Набор настроек, доступных разработчику в Express версии очень ограничен в сравнении с версией Professional. Например в ней нельзя управлять локализацией (в Professional можно), а так же нельзя отключить опцию, благодаря которой в результирующий файл справки записывается информация и обо всех файлах, входящих в состав проекта, для которого генерируется справка. Информация о файлах не нужна абсолютно. 

Запуск генерации справочной системы для Express версии доступен только из командной строки. Это не сложно, благо, что нужная команда находится на первой же странице в справке Doc-o-Matic Express. Я сохранил нужную мне строку записи в текстовый файл, дабы не набирать  её каждый раз - ею и пользовался. В принципе, за полчаса можно было бы написать и свой GUI для запуска, но это только в том случае, если бы я решил остаться на Doc-o-Matic Express.

Навигация в документации, полученной в Doc-o-Matic Express мне не понравилась. Обычно, в большинстве справочных систем слева имеется древовидная структура, с помощью которой можно перейти в нужный раздел справки. Doc-o-Matic Express эту структуру не генерирует, а в версии Professional это реализовать можно.  Покажу маленький скрин одной из страниц справочной системы, сгенерированной с помощью Doc-o-Matic Express (со своими замечаниями):

Вывод

В принципе, если вам нужна только html-справка, то использовать Doc-o-Matic Express для документирования своего кода можно, ежели при этом закрыть глаза на ряд моментов. Ведь в конце-концов мы получим корректную справочную систему, пусть и не совсем удобную в плане навигации и имеющую некоторую лишнюю информацию - это своего рода плата за использование инструмента. Твёрдую тройку ему ставить можно смело.

Doc-o-Matic 7 Professional

Данная версия продукта весьма мощная и гибкая. Она мне сразу очень понравилась. Чем больше я ковырялся в её настройках, тем больше она мне нравилась. Эта версия может (теоретически) генерировать справочную систему в следующих форматах:

• html
• pdf
• rtf
• xml
• Windows help
• MS Visual Studio Help

В версии Doc-o-Matic можно легко добавлять нужные локализации, чтобы все стандартные фразы, встречающиеся в справке были на нужном нам языке - вся эта информация хранится в каталоге %ProgramFiles%\Doc-O-Matic 7 Professional\dictionaries.

Затем я стал генерировать отчёты различных форматов, и тут вся моя радость улетучилась... Оказалось, что теория с практикой практически не сходятся - генерация успешно (если это можно назвать "успешным" - см. далее) проходила только для нескольких форматов:

• html
• pdf
• xml

Для всех прочих форматов, как и в случае с Doc-o-Matic Express, в самом конце генерации вылетает ошибка. Тестировал я на тех же компьютерах, которые были указаны для Express-версии. Однако это далеко не всё... Генерироваться-то справка генерируется, но вот как? Для наглядности приведу пару скринов.

Это то, как выглядит вся кирилица в pdf-справке:

Как видите - вся строки текста, написанные на кирилице, пишутся в одной строке друг поверх друга (явный баг программы). 

Примечание

В настройках  Doc-o-Matic нужно кодировку обязательно выбирать кирилицу, иначе все русские буквы будут отображаться символом "?" .

Однако у нас остаётся ещё версия html. Может она будет выглядеть корректно? Как бы не так... Смотрим:

Как видим - здесь проблема иного рода (причём это на большинстве страниц справочной системы): Имена классов и параметров написаны абракадаброй! Хотя в исходниках они прописаны английскими буквами. Как видим - в html-справке кирилица отображается нормально, а латиница во многих местах (не везде), отображается некорректно. Это тоже явный баг программы.

Реакция службы технической поддержки Doc-o-Matic

Я написал (на английском) два письма в службу технической поддержки Doc-o-Matic, с указанием найденных мною проблем и с наглядными скринами, демонстрирующими их. Однако ответа, к сожалению, так и не последовало.

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

Т.о. нет никаких гарантий, что в ближайшее (да и не только в ближайшее) время Doc-o-Matic Professional будет пригоден для генерации русскоязычной справки. Продукт ужасно кривой и для генерации русскоязычной справки хоть как-то можно использовать лишь Express-версию, при этом получая результат далеко не самого лучшего качества, но, как говорят: на безрыбье и рак рыба... Покупка версии Professional - это 100% выброс денег на ветер, что, как я полагаю, уже и без моих комментариев вполне очевидно.

Кстати, давайте взглянем на окошко приветствия, появляющегося при старте Doc-o-Matic (с моим комментарием на нём):

В завершении о Doc-o-Matic

Удивительно: версия Professional стоит 999$ и абсолютно не пригодна к использованию для генерации русскоязычной справки, в то время как версия Express бесплатна и в состоянии генерировать сносную html-версию справочной системы. Это как раз тот случай, когда высокая цена вовсе не является гарантом качества.

=======================

Ладно, Doc-o-Matic мне не подходит, но ведь всё равно задачу генерации справочной системы на основе своего кода нужно как-то решать. Есть ли иные альтернативные продукты и желательно бесплатные? К счастью оказалось, что есть. 

Sandcastle

Думаю, что нет таких программистов, которые бы сомневались в том, что Майкрософт генерирует свою справочную систему программно, а не пишет её ручками. Мне удалось найти в MSDN ссылку на этот программный продукт - он называется Sandcastle. Именно с его помощью сгенерирована справочная система MSDN. Я скачал данную софтину, установил её и без каких либо проблем смог сгенерировать справочную систему в форматах html (вэб-сайт), asp.net (вэб-сайт), chm и HxS. Правда для того, чтобы я смог сгенерировать справку в формате chm, мне пришлось скачать из интернета и установить SDK 1.0 (именно 1.0, а не 1.1!!!) для MS Visual Studio 2008, поскольку в MS VS 2010 этот формат уже не поддерживается (это вам напишут при установке и предложат установить из инета недостающий контент, дав ссылку). Вы можете отказаться от установки указанного SDK - в этом случае вы не сможете генерировать справку в формате chm, но все остальные форматы будут доступны. 

Sandcastle генерирует справочную систему корректно, без всех тех ошибок, которые я показал выше в программе Doc-o-Matic. Не маловажным фактором является и то, что Sandcastle бесплатна.

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

Документация по AcadNetLib мною сгенерирована именно с помощью Sandcastle. Как только о первая версия библиотеки будет мною полностью дописана - я выполню более детальное комментирование исходного кода и пересоберу справочную систему этой библиотеки, дабы она (справка) была надлежащего качества.

Заключение

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

undefined