Настройка вывода Doxygen html - PullRequest
Новая
       8

Настройка вывода Doxygen html

1 голос
/ 21 декабря 2010

У нас есть формат заголовка функции, которому мы должны следовать.В основном это выглядит так: 

/**
* Name: blah
*
* Parameters:
*       int foo
*       bool bar
*
* .....

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

/**
* Name: blah
*
* Parameters:
*  \param  int foo
*  \param  bool bar
*
* .....

Когда Doxygen генерирует HTMLкомментарии, он добавляет заголовок параметров.У нас должна быть строка 4, так что это создает документы с двумя строками, в которых написаны параметры, первая из строки 4, а вторая автоматически вставляет Doxygen.

То, что я могу сделать, это либо иметь Doxygenигнорируйте строку 4 или добавьте, чтобы она не вставляла свой собственный заголовок «Parameters:».Кто-нибудь знает, возможно ли это?

1 Ответ

3 голосов
/ 21 декабря 2010

Простое решение - полностью удалить текст «Параметры:»;он полностью избыточен, так как разметка Doxygen делает совершенно ясным, что они являются параметрами!

В этом отношении, метка «Имя:» также полностью избыточна и заставляет вас поместить имя в оба комментария.и код.Зачем вам это нужно?Это имя прямо в коде.Это ненужная головная боль при обслуживании комментариев, и Doxygen будет использовать имя в коде, а не имя в комментарии в сгенерированной документации.

Если вы попытаетесь смешать существующий формат с форматом, совместимым с Doxygen, это будетпроще использовать строчные комментарии C ++ / C99, а не блокировать комментарии;большинство компиляторов C поддерживают их: 

// Name: blah
//
// Parameters:
/// \param  foo Description of foo
/// \param  bar Description of bar

Примечание \param <type> <name> неверный синтаксис Doxygen;это \param <name> <description>.Doxygen получает тип из кода;повторное указание типа в комментарии совершенно излишне, и еще одна головная боль при техническом обслуживании.

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

//! @brief  Brief description
//!
//! Full description if necessary.
//! @param p1    p1 description
//! @param p2    p2 description
//! @return Return value description
int foobar( int p1, int p2 ) ;

Очевидно, используете ли вы /// или //!и \ или @ - вопрос предпочтения.

...