Пункт 217. Документирование Apache HTTPD
Apache 2.4 использует Doxygen для документирования API и глобальных переменных в коде. Это объяснит основы того, как документировать с помощью Doxygen.
Краткое описание
Чтобы начать блок документации, используйте . /**
Чтобы завершить блок документации, используйте */
В середине блока есть несколько тегов, которые мы можем использовать:
Description of this functions purpose
@param parameter_name description
@return description
@deffunc signature of the function
Не deffunc всегда нужно. В DoxyGen нет полноценного синтаксического анализатора, поэтому любой прототип, использующий макрос в объявлении возвращаемого типа, слишком сложен для scandoc. Для этих функций требуется файл deffunc . Пример (с использованием > вместо >):
/**
* return the final element of the pathname
* @param pathname The path to get the final element of
* @return the final element of the path
* @tip Examples:
* <pre>
* "/foo/bar/gum" -> "gum"
* "/foo/bar/gum/" -> ""
* "gum" -> "gum"
* "wi\\n32\\stuff" -> "stuff"
* </pre>
* @deffunc const char * ap_filename_of_pathname(const char *pathname)
*/
В верхней части заголовочного файла всегда включайте:
/**
* @package Name of library header
*/
Doxygen использует новый файл HTML для каждого пакета. Файлы HTML называются {Name_of_library_header}.html, поэтому постарайтесь быть краткими в своих именах.
Для дальнейшего обсуждения возможностей обратитесь на сайт Doxygen.
