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

Question

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

, например:

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

Answer 1

Нет, Doxygen не поддерживает комментарии блоков внутри функциональных органов. Из инструкции по эксплуатации:

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

Раздел: Doxygen documenting the code

Answer 2

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

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

Answer 3

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

Answer 4

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

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

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

, который делает как:

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

• делают ОР1

• сделать ФП2

---

Edit:следующий комментарий Dana в Сане, по поводу моего понимания Doxygen документации и почему она не входит в противоречие с моим опытом.

Насколько я понимаю и интерпретирую документацию Doxygen, это не противоречит quote provided by Aaron Saarela. В начале звена он обеспечивает, есть пункт о документации кузова:

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

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

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

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