Комментарии doxygen

Документирование исходных кодов программы

При ведении коллективно разработки одной из задач программиста является оформление исходных текстов программ. Для решения этой задачи разработано множество программных продуктов, которые позволяют совместить процесс формирования документации по исходным кодам с процессом их написания. Т.е. входными данными для них являются сами исходные тесты программ, а на выходе формируется документация в заданном формате. Среди бесплатных продуктов можно назвать следующие: AsmDoc, AutoDOC, Autoduck, CcDoc, CppDoc, Cxref, cxxwrap, Cxx2HTML, C2HTML, Doc++, DocClass, Doxygen, DoxyS (Doxygen fork/spinoff), Epydoc, gtk-doc, HappyDoc, HeaderDoc, HTMLgen, HyperSQL, Javadoc, KDoc, Natural Docs, phpDocumentor, PHPDoc, ReThree-C++, RoboDoc, ScanDoc, Synopsis, Tydoc, VBDOX.

Ключевой особенностью всех этих программ является способность прочитать исходные тексты программы, выделить все классы, методы, атрибуты, функции, построить зависимости между ними, а также выделить из исходных текстов комментарии, которые оставили программисты с тем, чтобы поместить их в формальный документ, формируемый на выходе. Большинство генераторов документации ориентировано на использование определенных языков программирования. Например Javadoc разработан компанией Sun Microsystems для формирования документации по библиотекам программирования Java, которые они же и разработали. Вследствие этого Javadoc является де-факто стандартом оформления исходных текстов программ, написанных на языке Java.

Применительно к языку программирования C++ не существует единого стандарта оформления исходных тестов, однако наиболее распространенным средством является doxygen (http://www.stack.nl/~dimitri/doxygen/). Это средство реализовано для большинства операционных систем, включая MS Windows, Linux, MacOS. Следует заметить, что doxygen способен работать с исходными текстами полностью без комментариев, однако в этом случае в результирующем отчете будут присутствовать лишь формальные имена без описания назначения.

Doxygen по умолчанию игнорирует все комментарии в программе, за исключением специально выделенных следующими способами:

Комментарии, относящиеся к строке, следующей за ними:

/// Функция что-то делает

void func1(int param1);

/**

Функция делает что-то другое

*/

void func2(int param1);

Комментарий, относящийся к строке, в которой он находится:

void func1(

int param1 ///< Параметр предназначен для указания количества чего-то

);

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

Дата добавления: 2014-11-25