How to be able to extract comments from inside a function in doxygen?

Question

I'm interested to know if it is possible to have some comments in a function (c, c++, java) in a way that doxygen could put them in the generated html file.

for example:

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

Answer 1

No, doxygen does not support comments blocks inside function bodies. From the manual:

Doxygen allows you to put your documentation blocks practically anywhere (the exception is inside the body of a function or inside a normal C style comment block).

Section: Doxygen documenting the code

Answer 2

Comments inside the code are meant to explain a particular implementation snippet for another programmer to understand, not a feature of the function for users to read about.

If it has to be documented for users, it should be done ouside the function block, on a comment defining the interface (signature as well as preconditions, postconditions, usage examples or whatever you deem necessary).

Answer 3

Maybe instead you could put the code of function as an example. http://www.stack.nl/~dimitri/doxygen/commands.html#cmdexample

Answer 4

I don't know for C but I do it every day in Objective-C, where I have comments such as:

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

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

which renders as:

This method performs the following operations:

• do op1

• do op2

---

Edit: following comment by Dana the Sane, concerning my understanding of Doxygen documentation and why it is not in contradiction with my experience.

As far as I understand and interpret the Doxygen documentation, this is not in contradiction with the quote provided by Aaron Saarela. At the begining of the link he provides, there is a paragraph about in-body documentation:

For each code item there are two (or in some cases three) types of descriptions, which together form the documentation: a brief description and detailed description, both are optional. For methods and functions there is also a third type of description, the so called "in body" description, which consists of the concatenation of all comment blocks found within the body of the method or function.

This means that is it OK to put Doxygen documentation in a function or method body. This is what I described on top of my answer.

In my opinion, the paragraph quoted by Aaron refers to documentation which is usually put in front of function or method declaration or implementaiton. This is the one that describes parameters, return values and so on. That heading documentation cannot be put inside the body of a function or method.

But detailed documentation concerning each step of an algorithm inside a body is perfectly handled by Doxygen.