7

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();
}
INS
  • 10,594
  • 7
  • 58
  • 89
  • could you give a small example of what your code (with the comments) is supposed to look like and where in the documentation you think the comments should show? – lothar Apr 16 '09 at 21:12

4 Answers4

20

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.

Community
  • 1
  • 1
mouviciel
  • 66,855
  • 13
  • 106
  • 140
  • 1
    This is at odds with the documentation that Aaron links to above. Is the documentation out of date maybe? – Dana the Sane Apr 16 '09 at 22:03
  • 5
    IIRC, you do have to start the function's documentation outside the body, but it is ok to use a literate programming style where paragraphs about the function are interleaved with source through the function's body. Done with care, the result is eminently readable both in the source file and in the generated documentation. – RBerteig Apr 17 '09 at 08:49
8

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

albert
  • 8,285
  • 3
  • 19
  • 32
Aaron Saarela
  • 3,956
  • 1
  • 19
  • 17
5

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).

David Rodríguez - dribeas
  • 204,818
  • 23
  • 294
  • 489
  • +1 That's why I asked him for an example. To see who the audience of that comment might be. – lothar Apr 17 '09 at 00:35
  • 1
    How about this: If it is documented for users then it should be in the header file. If it is documentation for the maintainers then it should be in the c file, and even in the body of the code. – Michael Apr 30 '15 at 19:50
0

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

albert
  • 8,285
  • 3
  • 19
  • 32
Bastien Léonard
  • 60,478
  • 20
  • 78
  • 95