Как быть в состоянии извлечь комментарии изнутри функции в Doxygen?

Question

Мне интересно знать, возможно ли иметь некоторые комментарии в функции (c, c ++, java) таким образом, чтобы doxygen мог поместить их в сгенерированный html-файл.

например:

function(...)
{
do_1();
/**
 * Call do_2 function for doing specific stuff.
 */ 
do_2();
}

Answer 1

Я не знаю для C, но я делаю это каждый день в Objective-C, где у меня есть такие комментарии, как:

/// This method perform the following operations:
- (void) myMethodWith: (id) anObjectArgument
{
    /// - do op1
    [self op1];

    /// - do op2
    op2(anObjectArgument);
}

, который отображается как:

Этот метод выполняет следующие операции:

• do op1

• do op2

---

Редактировать: после комментария Даны, здравомыслящего, относительно моего понимания документации Doxygen и почему это не противоречит моему опыту. Насколько я понимаю и интерпретирую документацию по Doxygen, это не противоречит цитате , предоставленной Аароном Саарелой . В начале ссылки, которую он предоставляет, есть параграф о внутренней документации:

Для каждого элемента кода есть два (или в некоторых случаях три) типа описания, которые вместе образуют документация: краткое описание и подробное описание, оба необязательный. Для методов и функций есть также третий тип описание, так называемый "в теле" описание, которое состоит из объединение всех блоков комментариев находится в теле метода или функция.

Это означает, что все в порядке, чтобы поместить документацию Doxygen в тело функции или метода. Это то, что я описал в верхней части моего ответа.

По моему мнению, параграф, цитируемый Аароном, относится к документации, которая обычно ставится перед объявлением или реализацией функции или метода. Это тот, который описывает параметры, возвращаемые значения и так далее. Документация заголовка не может быть помещена в тело функции или метода.

Но подробная информация о каждом шаге алгоритма внутри тела прекрасно обрабатывается Doxygen.

Answer 2

Нет, doxygen не поддерживает блоки комментариев внутри тел функций. Из руководства:

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

Раздел: Doxygen, документирующий код

Answer 3

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

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

Answer 4

Может быть, вместо этого вы могли бы привести код функции в качестве примера. http://www.doxygen.nl/manual/commands.html#cmdexample