Doxygen in a .c-file

Question

I'm using doxygen to comment a pure C project. The documentation for a struct is of the following form:

 /** @struct cl_options
 *  @brief This structure contains all ...
 *  @var cl_options::input_file
 *  Member 'input_file' contains ...
 *  @var cl_options::output_file
 *  Member 'output_file' contains ...
 *  @var cl_options::bitrate_mode
 *  ...
 */
struct cl_options {
    FILE* input_file;
    FILE* output_file;
        ....
};

Nevertheless I get warnings:

.../commandline.c:39: Warning: Member input_file (variable) of class cl_options is not documented.
.../commandline.c:40: Warning: Member output_file (variable) of class cl_options is not documented.

and so on. For all the structures within the project.

There is a decleration in the header file commandline.h

struct cl_options;
typedef struct cl_options cl_options;

but the doxygen is in the .c-File.

Now the generated doxygen has a link for the struct in the data structures section but it is not documented. Instead there is a link which says

The documentation for this struct was generated from the following file: commandline.c

and then there is the documentation I provided in the .c-file. How can I avoid this?

aldr aldr · Accepted Answer · 2013-06-25T23:22:06

I noticed a lot of warnings myself, while using doxygen, however most of the time the output seemed to be fine with me. You can turn, different warnings on and off. For more information visit the doxygen manual and choose which warnings your want to be enable.

However, you can try to move your @var tags from your .c file to your .h header. Just leave the documentation of functionality from your struct, in your .c.

Also, you might want to take a look at this post, with a similar question.

using-doxygen-with-c-do-you-comment-the-function-prototype-or-the-definition? Or both?

Doxygen in a .c-file

1 Answers