Yurin's home page

My graduate students

How to program

Basic Literature

Important links

Some notes on Computer Vision topics

Current C++ codes

Research problems for students

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 = .. \
../src1 \
../src2 \
../header1
 

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

EXCLUDE_PATTERNS = a1.cpp;a2.cpp;a3.cpp    - поименно файлы, по которым документацию делать не надо.

EXAMPLE_PATH = .. \
../src1 \
../src2 \
../header1
 

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

IMAGE_PATH = .. \
../src1/img \
../header1/img
 

Если в документацию требуется включить поясняющие изображения - здесь указываются пути где они находятся.

DOT_PATH = C:/CC/Graphviz/bin

Указать путь, куда был поставлен пакет GraphViz, точнее файл dot.exe .
 

DOTFILE_DIRS = ../src1/dot \
../tests/dot
 

Если в документацию надо включить свои диаграммы (графы), что-то поясняющие - их можно сделать в формате *.dot (GraphViz), а в этом файле надо указать, где такие файлы лежат в проекте.


5) Находясь в каталоге, где лежит файл Doxyfile выполнить команду doxygen.exe

Все. После того как отработает - в подкаталогах окажется документация HTML.

В принципе, doxygen умеет создавать документацию в форматах RTF (Microsoft Word) , TeX, PS, вместе с HTML может быть подготовлен проект для перевода (с помощью программы HTML Help Workshop) набора  html файлов и изображений в единый сжатый файл *.chm

Если специально не указано (см. комментарии в файле Doxyfile и документацию к doxygen) - в документации будут отражены все созданные в проекте пространства имен, классы и функции. Показывать или нет закрытые функции классов и функции видимые только внутри отдельного файла (static) - можно указать, редактируя файл Doxyfile. Если заказано ( и в заказанном объеме) взаимосвязи между классами (наследование, включение) будет показано в документации в виде диаграмм- направленных графов. Это осуществляется с помощью вызовов программы GraphViz , которые выполнит сам doxygen.

Если был установлен TeX - то в комментариях в тексте программы можно писать не только текст, но и формулы, например:

/*!
* Вычисляет функцию Гаусса \f$ g(x)= exp( - {x^2 \over 2 \sigma^2 } ) \f$
***************************************************************************/
class Gauss
{
    //! Возвращает значение ф-ции Гаусса в точке x.
    float operator()(float x)

......