Система документирования ПО
DOC++
|
Курс посвящен
изучению средств автоматизированного документирования ПО на примере
свободно распространяемой системы doc++, позволяющей создавать
документацию для языков С/С++ и Java.
doc++ - это программа, которая из комментариев делает
документацию на
программу. Если начать комментарий с символов /// или /**, то doc++
будет
использовать его при написании документации. Документация может быть
выдана в
одном из двух форматов: TEX
и HTML. При этом в HTML документации формируются правильные
гиперссылки, так что, просматривая документацию на какую-нибудь функцию
и ткнув
в один из её параметров, мы можем сразу попасть на страницу,
описывающую данный
конкретный параметр. Удобно.Существует общеизвестное наблюдение: чтобы научить медведя открывать дверь, достаточно десяти минут. Научить медведя закрывать дверь не удастся никогда. Почему? У него нет в этом необходимости. Переложим его на программисткую среду: чтобы приучить программиста писать комментарии к программе, достаточно пары месяцев. Приучить программиста писать документацию к произведённому ПО не удастся никогда. Почему? У него нет на это времени. Известно, что документация бывает двух видов -- для пользователя и для других программистов. Назначение первой -- объяснить человеку, установившему программу, что "...у нея внутре анализатор и думатель...", и как этим анализатором и думателем пользоваться. Писать документацию для пользователя -- это искусство. По этой причине программисты к составлению такой документации привлекаются довольно редко (чаще - консультируют). Эта часть документации нас не волнует совершенно. Вторая разновидность документации предназначена для программистов, и нужна в случае, если кто-то захочет что-то в написанной программе поправить или что-то к ней дописать. Написание документации - работа нужная, но неблагодарная в основном потому, что документация имеет свойство устаревать. Между тем, в каждой программе (если, конечно, написал её нормальный программист) в комментариях к исходным текстам содержится вся исчерпывающая документация. Начинающего программиста с детства учат (и в большинстве случаев таки приучают) внятно документировать произведения своего программистского искусства. Нормальный программист пишет и правит комментарии вместе с кодом программы, так что информация в комментариях (как правило) соответствует комментируемому коду. Информация в комментариях весьма подробна. Необходимо только эти комментарии собрать в одном месте и немного структурировать. Такую работу можно сделать автоматически. Для её выполнения есть специальные программы, одной из которых является doc++. Дополнительную информацию по doc++ можно найти на домашней странице проекта. Пример HTML-документации, сгенерированной при помощи doc++ можно посмотреть здесь. Версию doc++ для Windows можно взять здесь. Далее мы будем называть документ, создаваемый doc++ справочником. |
Содержание |
Задания , помеченные символом "!" являются дополнительными и не обязательны для сдачи лабораторной работы. |
copyright © кафедра «Системное программирование» |