Про документацию (продолжение)

На этот раз без лишних размусоливаний. Как известно, сейчас chm уже не так моден как раньше, а модно что-то на подобии MSDN желательно еще и встроенное в это самое MSDN.

И собственно тот набор xslt, которые я рекламировал в предыдущем сообщении, генерируют набор html и кое-какой дополнительной ерунды как раз, чтобы компилировать ее при помощи MSHelp 2.0. Я попробовал - тоже не плохо. Не очень понятно как оно при этом с портируемостью на разные машины, но думаю, что если и сложнее чем с chm, то не намного.

Значит план действий такой.

Заходим в MSVisual Studio, главное меню, File\New\Project\, в появившемся диалоге смотрим есть ли в дереве папка Other Projects\Help Projects\, а в ней вот такие вот шаблоны проектов:




Если их там не оказалось. Качаем Visual Studio .NET Help Integration Kit 2003. (Это ссылка на тот, который для MSVS 2003, для MSVS 2005 тоже есть, и google наверняка знает где.)

Ставим эту милую приблуду. Она встраивается в Visual Studio. Теперь можно создать проект Help-а. Создаем, добавляем туда все html и прочую ерунду, аналогично тому как мы делали для chm. Компилируем. Дивимся на результат.

Про документацию

Решил, что совсем неплохо было бы задокументировать то, что есть на данный момент в STDU Viewer. А как минимум COM-объекты (конечное приложение документировать особого смысла нет)

В результате хотелось получить, что-то похожее на MSDN (потому что мне нравиться MSDN, ага).

План действий такой.

Этап первый

Обрабатываем исходники doxygen-ом. Только генерим не html (он получается не совсем такой какой хочется), а xml.

Здесь надо учесть, что doxygen не очень хорошо понимает макросы типа STDMETHOD и т.п., а так же испытывает проблемы с такими ключевыми словами как __interface, которые используются в attributed dll-s. А у меня dll-ки именно что attributed.

Большая часть проблем решается стандартным для doxygen способом - в конфигурационном файле, прописываем параметр PREDEFINED. Получается что-то вроде:

PREDEFINED           = "DECLARE_INTERFACE(name)=class name" \
                       "STDMETHOD(result,name)=virtual result name" \
                       "PURE= = 0" \
                       . . .

К сожалению, это не решает все проблемы. Например, при описании интерфейса в attributed dll у нас имеются строчки типа:

[id(200), propget] HRESULT PageFormat([in] long Index, [out, retval] long *pVal);

В реализации (классе наследованном от этого интерфейса), это будет выглядеть уже так

STDMETHOD(get_PageFormat)(long Index, long *pVal)

а после замены doxygen-ом макроса STDMETHOD(get_PageFormat) на virtual HRESULT get_PageFormat, мы получим нормальный метод, но этого метода нет в интерфейсе, соответственно, в документации отобразиться не правильное наследование, ну и пошли поехали проблемы.

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

С первым этапом все.

Этап второй

Если все прошло гладко, то в результате работы doxygen мы получили набор xml файлов.
Теперь надо преобразовать их в html я пользовался набором xslt шаблонов вот отсюда (там кстати есть add-on под Visual Studio, вот только он под VS2005, а я, на своих проектах, до сих пор сижу на 2003-ей и перелезать особого смысла не вижу).

Чтобы применить шаблоны к xml нам понадобиться какая-нибудь программа, осуществлющая эту затейливую операцию. Правильнее всего воспользоваться nsxlt.exe, как это предлагается на сайте где брались xslt шаблоны, а можно написать свою.

Итак запускаем, применяем, получаем набор html-файлов.

Этап третий

Он самый короткий, создаем chm файл. Можно ручками (но лучше таки программно) создать проект, добавить туда все html, полученные на предыдущем этапе, и не забыть css и картинки. Компилим с помощью hhc.exe. И наслаждаемся.

Теперь немного лирических замечаний.

Чем хорош способ?

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

1. загрузить конфигурацию doxygen, добавить/удалить файлы по которым будем строить документацию, сохранить конфигурацию.

2. запустить последовательно doxygen, и программу конвертирующую xml в html.

3. сгенерировать проект для создания chm (чтобы не добавлять html руками) и запустить chm-компилятор.

Т.е. практически все на автомате.

Во-вторых, система позволяет документировать код, не отвлекаясь от его написания. Не писать комментарии в коде можно только в случае, если уверено полагаешь, что после того как код написан и сдан, его уже никогда не придется править (более точно никогда не придется править тебе :) ). Такая наивность жестоко наказывается реальностью. Если же детство уже прошло, то комментировать код будешь так или иначе, и совсем не сложно приучить себя комментировать его с учетом синтаксиса doxygen.

В-третьих, то что получается в результате, лично мне, очень нравится.

Чего пока не хватает?

Надо прикрутить автоматическую или полуавтоматическую генерацию оглавления в chm файле. Думаю это не сложно сделать, но пока руки не дошли поковыряться.

Надо посмотреть возможность добавить страницы с общим описанием, т.е. не привязанным к конкретным классам, методам и т.п. Тоже пока просто не пробовал.

Надо несколько упорядочить описания. Пока на главной странице все свалено в один список, интерфейсы, классы, причем из всех длл-к. Это не шибко удобно. Мысли про варианты решения есть, но надо пробовть.