Документ взят из кэша поисковой машины. Адрес
оригинального документа
: http://imaging.cs.msu.ru/~yurin/HowTo_document_programs.html
Дата изменения: Mon Nov 24 13:02:07 2008 Дата индексирования: Mon Oct 1 19:44:29 2012 Кодировка: Windows-1251 |
Home People Activities Research Publications |
|
Dmitry V. Yurin personal pageКак программировать, на чем, что читать, какие пакеты использовать:Что читать по программированию
Как документировать программыПрограммы, а предмет нашей деятельности это алгоритмы обработки изображений, и как было сказано выше для них наиболее разумный выбор - С++, необходимо документировать. Иначе потом самому невозможно разобраться что, зачем и почему написано. Часто программы получаются большими, и неплохо бы иметь возможность обозреть взглядом, какие пространства имен и зачем введены, какие в них есть классы и функции. Правильное решение - система автоматического документирования DOXYGEN. Эта программа понимает много различных языков программирования, в том числе и С++. Должным образом (и весьма простым!) оформленные комментарии переносятся из кода программы в генерируемый Help. Система анализирует исходные файлы проекта и собирает списки Пространств имен Классов Функций Переменных Взаимосвязи между ними (может строить и графические диаграммы наследования, включений и т.п. (для построения диаграмм используется программа GraphViz) Можно писать свои расширенные комментарии с формулами (для этого придется поставить TeX) Все перечисленные программы официально являются бесплатными и существуют как для Windows так и UNIX, причем полностью совместимы. Скачать программы можно по адресу: doxygen: http://www.stack.nl/~dimitri/doxygen/download.html GraphViz: http://www.graphviz.org/Download..php TeX: http://miktex.org/Setup.aspx В простейшем варианте для того чтобы перенести комментарии из текста в программе в сгенерированный Help надо: 1) Установить указанные программы, 2) Поместить в текст программы комментарии перед объявлениями пространств имен, классов, функций (как глобальны, так и функций-членов классов. 2) Оформление комментария несколько отличается от принятого в С++, но полностью совместимо. Вместо // следует писать //!, вместо /* */ следует писать /*! */ . 3) создать в проекте подкаталог, например doc и скопировать туда файл Doxyfile 4) Внести в этот файл изменения: PROJECT_NAME = "My project name" - вписать названия своего проекта. PROJECT_NUMBER = "Version 1.01" - вписать номер версии своего проекта.
INPUT = .. \ относительно положения файла Doxyfile - прописать пути где находятся файлы проекта, которые надо включить в документацию. Обратный слэш - указывает, что следующая строка является продолжением. В путях следует использовать прямые слэши. EXCLUDE_PATTERNS = a1.cpp;a2.cpp;a3.cpp - поименно файлы, по которым документацию делать не надо.
EXAMPLE_PATH = .. \ Если в документации будут приводиться примеры использования каких либо компонентов проекта (функций классов) и другие пояснения - здесь прописать пути каталогов, где лежат соответствующие файлы.
IMAGE_PATH = .. \ Если в документацию требуется включить поясняющие изображения - здесь указываются пути где они находятся. DOT_PATH = C:/CC/Graphviz/bin
Указать путь, куда был поставлен пакет GraphViz,
точнее файл dot.exe .
DOTFILE_DIRS = ../src1/dot \
Если в документацию надо включить свои диаграммы (графы), что-то поясняющие
- их можно сделать в формате *.dot (GraphViz),
а в этом файле надо указать, где такие файлы лежат в проекте. Все. После того как отработает - в подкаталогах окажется документация HTML. В принципе, doxygen умеет создавать документацию в форматах RTF (Microsoft Word) , TeX, PS, вместе с HTML может быть подготовлен проект для перевода (с помощью программы HTML Help Workshop) набора html файлов и изображений в единый сжатый файл *.chm Если специально не указано (см. комментарии в файле Doxyfile и документацию к doxygen) - в документации будут отражены все созданные в проекте пространства имен, классы и функции. Показывать или нет закрытые функции классов и функции видимые только внутри отдельного файла (static) - можно указать, редактируя файл Doxyfile. Если заказано ( и в заказанном объеме) взаимосвязи между классами (наследование, включение) будет показано в документации в виде диаграмм- направленных графов. Это осуществляется с помощью вызовов программы GraphViz , которые выполнит сам doxygen. Если был установлен TeX - то в комментариях в тексте программы можно писать не только текст, но и формулы, например:
/*!
|