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

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

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

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

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

Когда Doxygen генерирует html-комментарии, он добавляет заголовок «Параметры». Нам требуется строка 4, поэтому создаются документы с двумя строками, в которых говорится «Параметры», первая из строки 4, а вторая Doxygen автоматически вставляет.

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


c comments doxygen
person Andy    schedule 20.12.2010    source источник

Ответы (1)


arrow_upward
3
arrow_downward

Простое решение — полностью удалить текст «Параметры:»; это совершенно избыточно, поскольку разметка 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 получает тип из кода; снова указание типа в комментарии совершенно избыточно и еще одна головная боль обслуживания.

Я настоятельно рекомендую вам использовать более 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 ) ;

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

person Clifford    schedule 20.12.2010
comment
Я собираюсь посмотреть, возможно ли это, но, вероятно, это потребует слишком много бумажной работы (это код, достойный полета), я уверен, что они будут утверждать, что хотят, чтобы его читали без каких-либо знаний о Doxygen. Конечно, я думаю, что любой, кто может понять источник, должен быть в состоянии сделать вывод, что представляют собой теги Doxygen. - person Andy; 21.12.2010
comment
@Andy: Хотя я считаю, что стандарты кодирования важны, к сожалению, ваш существующий стандарт был так плохо разработан (путем дублирования информации, которая неявна, и, по крайней мере, в вашем примере не содержится реальной полезной информации, которой еще нет в коде). Изменение этого было бы к лучшему в долгосрочной перспективе IMO. Конечно, тогда вам придется подумать, что делать со всем унаследованным кодом — изменить его или пойти на уступку. При последовательном применении его изменение может быть запрограммировано. - person Clifford; 21.12.2010
comment
На самом деле удалось уговорить их на реструктуризацию заголовков функций! Мы используем комментарии в формате xml, чтобы при необходимости мы могли анализировать информацию с помощью других сторонних инструментов. - person Andy; 28.12.2010
comment
@Энди: Интересно; вы знаете, что Visual Studio уже определяет формат комментариев XML для документации? Возможно, стоит использовать их теги: msdn.microsoft.com/en-us/ журнал/cc302121.aspx. Однако проблема с XML, конечно, заключается в налоге на угловую скобку (codinghorror.com/blog/2008/05/xml-the-angle-bracket-tax.html) - person Clifford; 29.12.2010
comment
Да, я использовал большинство тегов, которые определяет Visual Studio. Doxygen подхватывает большинство из них. Мы немного потеряли читабельность, но я чувствую, что преимущества перевешивают недостатки. - person Andy; 04.01.2011