PasDoc, ROBODoc, DocBook. Документирование кода в Delphi / Delphi

PasDoc, ROBODoc, DocBook. Документирование кода в Delphi

Некоторое время назад передо мной стоял выбор средства документирования исходных текстов на Dephi.

Документировать код во внешних файлах весьма трудоемкая задача. Вопрос синхронизации кода и документации весьма важен и потому средства типа MS Word, OpenOffice.org и даже Help & Manual не подходят однозначно.

Программисты Java имеют хорошую утилиту javadoc, позволяющую генерировать документацию прямо по вставленным в код комментариям особого формата. Существует такой аналог и для Delphi: pasdoc
ROBOdoc - еще одна подобная утилита, но этот вариант я отбросил сразу из-за неоправданно усложненного синтаксиса и слишком большей расхожести с javadoc. Да и общая ориентация утилиты несколько отталкивала. Немаловажным фактором являлось и то, что языком написания был C, а значит могли быть трудности с пониманием работы и исправлением ошибок.

Pasdoc – это OpenSource программное обеспечение распространяемое под GNU Public license. Тоесть вы можете делать с программой и кодом все, что угодно, кроме присвоения авторских прав

Долгое время pasdoc'у вменяли в вину то, что он не способен генерировать формат DocBook. Собственно DocBook не являться конечным форматом документации и в чистом виде не используется.
DocBooc - SGML или XML (проще говоря — популярный набор тегов), предназначенное для разметки документов, такое же, как HTML для разметки веб-документов. (C) Wikipedia
DocBook – интересен тем, что позволяет вести единый файл документации и получать документы или их части в различных форматах: html, pdf, WinHelp, CHM.
На самом деле, это неправда. Вернее, полуправда Написание документации в этом формате занятие весьма утомительное без специальных средств предоставляющих сервис: форматирования исходного кода, проверки синтаксиса, проверки правописания и тому подобного.

«В чем сила, брат ...?» (С) Брат 2. ... «А сила она в XML...» (C) ХЗ
Сила DocBook'а в XSL схемах которые поддерживаться сообществом и являться инструкциями для процессоров преобразующих XML файл в другой тестовый файл.

Судите сами.
HTML: DocBook > XSL схема > процессор > HTML
WinHelp: DocBook > XSL схема > процессор > файлы проекта для MS HelpWorckshop> MS HelpWorckshop компилятор>HLP
PDF: DocBook > XSL схема > процессор > XSL-FO>Форматировщик (Apache FOP, XEP etc.)>PDF

Ключевым звеном являются набор схем, которые только подготавливают необходимые входные файлы. Тоесть, теоретически можно написать схему которая бы на выходе дала исходные коды приложения на Dephi и сразу же скомпилировать утилиту показывающую справку как приложение %-)

Почему я решил написать статью.
PasDoc объявил о поддержке формата SimpleXML!
Для «тех кто в танке», прошу прощения, поясню. На выходе утилита выдаст структурированный XML вашего кода. А теперь вернемся на пару строк вверх и в схему вместо DocBook поставим SimpleXML. Что получим ? Ну практически ничего, потому как DocBook XSLStylesheet ничего не знают о SimpleXML.
Поскольку я математик, то вспоминается:
Физику и математику ставится задача: написать алгоритм кипячения воды в чайнике на газовой плите.
Ответ одинаковый у обоих: Налить воду, зажечь огонь, поставить на него чайник и ждать.
Теперь усложним задачу: в чайнике уже есть вода.
Физик: зажечь огонь, поставить на него чайник и ждать.
Математик: вылить воду, задача сводиться к предыдущей.

Получаем: SimpleXML>XSL-SimpleXML2DocBook> Processor>DocBook –> а для DocBook задача у на уже решена.
Упреждая вопросы: почему не pasdoc > DocBook, отвечаю, что не DocBook это довольно мощная и развитая система и не всякому проекту подходит по масштабам. Потому гораздо эффективней иметь «сырой» XML и уже из него получать форматирование DocBook.

Существует и второй метод решения задачи. SimpleXML2>XSLMyStyleSheet>...
Создать собственные схемы преобразования. Может быть и трудоемко, но получим возможность конвертировать прямо в формат внутреннего Wiki например.
IMHO написать свои схемы проще чем изучить теги DocBook.

Для тех, кто все таки дочитал до этой строки скажу, что SimpleXML не доступен в версии 0.10.0 и необходимо взять сборку с SVN. SimpleXML еще не совсем доработан. Для простоты показа примеров выкладываю скомпилированную мною версию и включаю ее в архив.

Архив содержит пример преобразования извлеченного из pas файла xml в html. Используется java-based процессор Saxon и Apache Ant. Потому приодеться установить Java.
Можно поспорить в выборе процессора. Существует XSLProc, он чуть быстрее, но и слабее потому, что не поддерживает XSL 2.0

Почему я выбрал Saxon, потому, что он пока единственный, кто поддерживает XSL 2.0, хотя я могу и ошибаться. К тому же он прекрасно интегрируется c Ant, а почему я выбираю Ant читайте тут(ссылка на статью в блоге).

Призываю энтузиастов владеющих XSL присоединяться разработке схем для других форматов

З.Ы. Фактически pasdoc может выбросить все форматы и оставить только xml %-) Тоесть оставить только функции извлечения данных из исходных текстов Delphi.
Задача трансформации в другие форматы у нас уже решена ...

З.Ы. З.Ы Будучи на разработчиком Delphi CodeGear (Borland) я бы не изобретал системы справки, а просто внедрил pasdoc и генерировал бы справку на лету в отдельном окне прямо в IDE как это реализовано в Lazarus.

Ссылки:
Пример к статье

http://pasdoc.sipsolutions.net/
http://www.xs4all.nl/~rfsber/Robo/robodoc.html
http://docbook.sourceforge.net/
Автодокументация исходников посредством PasDoc