Как иметь возможность извлекать комментарии изнутри функции в doxygen?

StackOverflow https://stackoverflow.com/questions/758045

Вопрос

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

например:

function(...)
{
do_1();
/**
 * Call do_2 function for doing specific stuff.
 */ 
do_2();
}
Это было полезно?

Решение

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

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

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

Другие советы

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

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

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

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

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

  • выполните операцию 1

  • выполните операцию 2

Редактировать: следующий комментарий Даны the Sane, касающийся моего понимания документации Doxygen и почему это не противоречит моему опыту.

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

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

Это означает, что можно ли помещать документацию Doxygen в тело функции или метода.Это то, что я описал в дополнение к своему ответу.

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

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

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

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

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

Лицензировано под: CC-BY-SA с атрибуция
Не связан с StackOverflow
scroll top