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?
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?
Related
Doxygen is able to document structs but it's not exporting any function declarations or macro definitions.
For instance these defined in headers are not exported.
/** Total instances */
#define TOTAL 10
/** Initializer */
void InitProduct(Product *product, const char *productName);
I'm using Doxygen GUI on Windows, appreciate a GUI reference.
Doxygen is fussy about what documentation it extracts when not EXTRACT_ALL.
Structures and classes are generally okay; functions and variables not so.
To get documentation extracted for functions and variables at the file-level scope, there needs to be a #file documentation element in that file:
/** #file frobulator.c
* Optionally describe the file...
*/
/** #brief My Frobulator.
*/
void frobulator () { ... }
This is for both headers and source files.
For functions and variables at namespace scope, the namespace also needs to be documented with #namespace or in situ. Unlike other elements, namespaces have no "single" point of declaration where documentation can be placed. I usually end up creating a separate .dox file to contain #namespace docs in C comment blocks.
Is it possible in Doxygen to add a brief description of a struct declared but not defined? For example, running doxygen <config file> (where <config file> is the configuration file with default parameters) in the folder with the file mydefinition.h
#ifndef MYDEFINITION_H_
#define MYDEFINITION_H_
/** My super secret structure you can't access fields */
struct MyStructure;
/** The function that lets you use any instance of 'struct MyStructure'
* #param msobj the object
*/
void functionUsingMyStructure(struct MyStructure* msobj);
will generate the documentation of the functon but not the documentation of the structure.
I tried to modify the configuration file of Doxygen by setting OPTIMIZE_OUTPUT_FOR_C = YES but it doesn't change the situation.
Doxygen ignores forward declarations of structs. To workaround this, you have to explicitly state that the given comment block describes your struct.
/** #struct MyStructure
* My super secret structure you can't access fields
*/
struct MyStructure;
As the title suggests, I want to enforce source code documentation for a C project managed in Subversion.
My idea is: set up a pre-commit hook that use doxygen for checking files with this options
WARNINGS = YES
WARN_IF_UNDOCUMENTED = YES
WARN_IF_DOC_ERROR = YES
WARN_NO_PARAMDOC = YES
The problem is: in order to have doxygen take into account a source file and raise warnings for undocumented members, It seems I must put into that file the "\file" documentation block as you see below.
/** \file foo.h
* A file for testing how to enforce documentation
*
* if I don't put voluntarily this first "file" block,
* doxygen "ignores" the file and does not generate the warnings
* I would expect (note that otherfunction is not documented)
*/
#ifndef FOO_H_
#define FOO_H_
/**
* \brief my test function
* \param msg a simple string
* \return 0 if ok, 1 if not ok
*/
int testFunction(const char *msg);
int otherFunction(const char *msg);
#endif
If I don't doxygen "ignores" the file and no warning is raised.
This makes the check uneffective: users can easily forget to put the required block at the beginning of the source and commit without control.
Is there a way to make doxygen enforce the /file block in the beginning of the file?
This issue is due to doxygen parsing constraints. I am using doxygen 1.8.11 with Eclox (the eclipse plugin) in Kinetis Design Studio for embedded C development.
Almost all of the doxygen compiling works, except I need to have a few very large static arrays. I didn't want to clutter up the main code, so I used a hack I found on these forums (https://stackoverflow.com/a/4645515/6776259):
static const float Large_Array[2000] = {
#include "Comma_Delimited_Text_File.txt"
};
Unfortunately, that hack is causing the compile of my main.c main_module group to fail. With the following error:
warning: end of file while inside a group
I've tried excluding those constants from my main_module group with something like the following:
/*!
** #addtogroup main_module
** #{
*/
...
... header code ...
...
/*!
** #}
*/
static const float Large_Array[2000] = {
#include "Comma_Delimited_Text_File.txt"
};
/*!
** #addtogroup main_module
** #{
*/
...
More code, definitions, etc.
None of this is generated in the doxygen compile...?
/*!
** #}
*/
This gets rid of the doxygen compiling error, but the compiled doxygen documentation does not include anything after the Large_Array declaration. So it seems the second #addtogroup statement is not working.
Am I missing something simple? Any help is appreciated. Thank you.
If Comma_Delimited_Text_File.txt doesn't have trailing linebreak, then try adding one.
Doxygen gets confused if include file doesn't end with linebreak. This can break the document generation for other files too, even when they don't seem related. Often this results in missing symbols and broken callgraphs.
I'm creating a module in C. When I refer to that module in the documentation, I want a link to the header file, not the struct (because the functions and other useful information are at the file level).
The file my_iterator.h contains
typedef struct {
int foo;
int bar;
} my_iterator_t;
I would like references to my_iterator to create a link to my_iterator.h. For example,
/**
Create a new, specially configured my_iterator
*/
my_iterator_t* special_factory_in_another_module();
Putting "my_iterator.h" in the documentation would create the correct link, but would sound strange. Putting my_iterator_t in the documentation would sound better, but not link to a useful place.
Although it is a bit verbose, this does what I want:
/**
* Create a new, specially configured [my_iterator](#ref my_iterator.h)
*/
my_iterator_t* special_factory_in_another_module();