CODEWITHSUNDEEP
cdoxygen
Gus
Gus

Reputation: 31

How to document with Doxygen a file include

I have some includes in the source code where I want to add some "to do".

For example:

/** \todo Review. */
#include "anyfile.h"

/** todo Another to do. */
#define ANY_MACRO 1

The problem is that the first "to do" is inserted in the macro definition and not in the include, as followed:

-----------------------------------
**Todo List**

Global **ANY_MACRO**

Review.

Another to do.

-----------------------------------

Any idea how to solve this ?

Upvotes: 2

Views: 2210

Answers (1)

Bentoy13
Bentoy13

Reputation: 4956

Following the online doc:

Let's repeat that, because it is often overlooked: to document global objects (functions, typedefs, enum, macros, etc), you must document the file in which they are defined.

Then I handle your problem in the following manner: I must have a \file comment in both files, and above the include line, I mention that the todo part refers to the included file.

In other words, I write this in my source file afile.c:

/** \file anyfile.h
 *  \todo Review
 */
#include "anyfile.h"

/** \file afile.c
 *  \brief Some code
 */

/** \todo wait, a todo !*/
#define A_MACRO

int main()
{}

In the included file, I write a short comment about the file itself:

/** \file anyfile.h 
 *  Very interesting header
 */

#define B_MACRO

As output, the todo comment is placed in the doc page of the included file. The awkward part according to me is that I have to put the block /** \file afile.c */ after the include line, otherwise it doesn't work.

Upvotes: 1

Related Questions